gateframe 0.1.0__tar.gz

gateframe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Practical Mind
+
+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.

gateframe-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: gateframe
+Version: 0.1.0
+Summary: Behavioral validation for LLM outputs in production workflows.
+License-Expression: MIT
+Keywords: llm,validation,behavioral,workflow,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: structlog>=23.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# Gateframe
+
+Behavioral validation for LLM outputs. Not schema validation - tools like Instructor and Pydantic AI already handle that. gateframe validates whether an LLM output *behaves correctly* given the context it was generated in, stays within decision boundaries, and fails in ways your system can recover from.
+
+```python
+from pydantic import BaseModel
+from gateframe.core.contract import ValidationContract
+from gateframe.core.failure import FailureMode
+from gateframe.rules.structural import StructuralRule
+
+class TriageOutput(BaseModel):
+    severity: str
+    recommendation: str
+    confidence: float
+
+contract = ValidationContract(
+    name="triage_check",
+    rules=[
+        StructuralRule(schema=TriageOutput),
+    ],
+)
+
+result = contract.validate({
+    "severity": "high",
+    "recommendation": "Escalate to on-call engineer",
+    "confidence": 0.92,
+})
+
+assert result.passed
+```
+
+When validation fails, you get structured failure records - not just a boolean:
+
+```python
+result = contract.validate({"severity": "high"})
+
+assert not result.passed
+for failure in result.failures:
+    print(failure.message)
+    # structural:TriageOutput failed: recommendation: Field required; confidence: Field required.
+```
+
+## Failure modes
+
+gateframe distinguishes four failure modes instead of binary pass/fail:
+
+**HARD_FAIL** - Stop execution, escalate. The output is wrong in a way that cannot be auto-recovered.
+
+```python
+# Missing required fields in a medical triage output
+StructuralRule(schema=TriageOutput, failure_mode=FailureMode.HARD_FAIL)
+```
+
+**SOFT_FAIL** - Flag the output and continue with degraded confidence. Something is off but not critical.
+
+```python
+# Output has all fields but confidence is below threshold
+StructuralRule(schema=TriageOutput, failure_mode=FailureMode.SOFT_FAIL)
+```
+
+**RETRY** - Re-prompt with failure context. The output is fixable by trying again.
+
+```python
+# Malformed JSON that might parse on a second attempt
+StructuralRule(schema=TriageOutput, failure_mode=FailureMode.RETRY)
+```
+
+**SILENT_FAIL** - The most dangerous kind. Output looks valid but violates semantic or boundary rules. gateframe makes these visible instead of letting them pass through.
+
+## When to use gateframe
+
+Use it when:
+- You need to validate LLM outputs beyond schema checks - behavioral contracts, decision boundaries, cross-step propagation
+- You need structured failure records for debugging production incidents
+- You want to distinguish between "retry this", "flag this", and "stop everything"
+
+Don't use it when:
+- You only need schema extraction from LLM outputs (use Instructor or Pydantic AI)
+- You need offline model evaluation or benchmarking (use DeepEval or RAGAS)
+- You need content safety filtering (use a dedicated guardrails tool)
+
+## Installation
+
+```bash
+pip install gateframe
+```
+
+For development:
+
+```bash
+git clone https://github.com/practicalmind-ai/gateframe.git
+cd gateframe
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from pydantic import BaseModel
+from gateframe.core.contract import ValidationContract
+from gateframe.rules.structural import StructuralRule
+from gateframe.audit.log import AuditLog
+
+# Define your expected output schema
+class AgentResponse(BaseModel):
+    action: str
+    reasoning: str
+
+# Create a contract with rules
+contract = ValidationContract(
+    name="agent_response_check",
+    rules=[StructuralRule(schema=AgentResponse)],
+)
+
+# Validate LLM output
+result = contract.validate({
+    "action": "send_email",
+    "reasoning": "User requested a follow-up email to the client.",
+})
+
+# Log the validation event
+audit = AuditLog()
+audit.record(result)
+```
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

gateframe-0.1.0/README.md

@@ -0,0 +1,135 @@
+# Gateframe
+
+Behavioral validation for LLM outputs. Not schema validation - tools like Instructor and Pydantic AI already handle that. gateframe validates whether an LLM output *behaves correctly* given the context it was generated in, stays within decision boundaries, and fails in ways your system can recover from.
+
+```python
+from pydantic import BaseModel
+from gateframe.core.contract import ValidationContract
+from gateframe.core.failure import FailureMode
+from gateframe.rules.structural import StructuralRule
+
+class TriageOutput(BaseModel):
+    severity: str
+    recommendation: str
+    confidence: float
+
+contract = ValidationContract(
+    name="triage_check",
+    rules=[
+        StructuralRule(schema=TriageOutput),
+    ],
+)
+
+result = contract.validate({
+    "severity": "high",
+    "recommendation": "Escalate to on-call engineer",
+    "confidence": 0.92,
+})
+
+assert result.passed
+```
+
+When validation fails, you get structured failure records - not just a boolean:
+
+```python
+result = contract.validate({"severity": "high"})
+
+assert not result.passed
+for failure in result.failures:
+    print(failure.message)
+    # structural:TriageOutput failed: recommendation: Field required; confidence: Field required.
+```
+
+## Failure modes
+
+gateframe distinguishes four failure modes instead of binary pass/fail:
+
+**HARD_FAIL** - Stop execution, escalate. The output is wrong in a way that cannot be auto-recovered.
+
+```python
+# Missing required fields in a medical triage output
+StructuralRule(schema=TriageOutput, failure_mode=FailureMode.HARD_FAIL)
+```
+
+**SOFT_FAIL** - Flag the output and continue with degraded confidence. Something is off but not critical.
+
+```python
+# Output has all fields but confidence is below threshold
+StructuralRule(schema=TriageOutput, failure_mode=FailureMode.SOFT_FAIL)
+```
+
+**RETRY** - Re-prompt with failure context. The output is fixable by trying again.
+
+```python
+# Malformed JSON that might parse on a second attempt
+StructuralRule(schema=TriageOutput, failure_mode=FailureMode.RETRY)
+```
+
+**SILENT_FAIL** - The most dangerous kind. Output looks valid but violates semantic or boundary rules. gateframe makes these visible instead of letting them pass through.
+
+## When to use gateframe
+
+Use it when:
+- You need to validate LLM outputs beyond schema checks - behavioral contracts, decision boundaries, cross-step propagation
+- You need structured failure records for debugging production incidents
+- You want to distinguish between "retry this", "flag this", and "stop everything"
+
+Don't use it when:
+- You only need schema extraction from LLM outputs (use Instructor or Pydantic AI)
+- You need offline model evaluation or benchmarking (use DeepEval or RAGAS)
+- You need content safety filtering (use a dedicated guardrails tool)
+
+## Installation
+
+```bash
+pip install gateframe
+```
+
+For development:
+
+```bash
+git clone https://github.com/practicalmind-ai/gateframe.git
+cd gateframe
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from pydantic import BaseModel
+from gateframe.core.contract import ValidationContract
+from gateframe.rules.structural import StructuralRule
+from gateframe.audit.log import AuditLog
+
+# Define your expected output schema
+class AgentResponse(BaseModel):
+    action: str
+    reasoning: str
+
+# Create a contract with rules
+contract = ValidationContract(
+    name="agent_response_check",
+    rules=[StructuralRule(schema=AgentResponse)],
+)
+
+# Validate LLM output
+result = contract.validate({
+    "action": "send_email",
+    "reasoning": "User requested a follow-up email to the client.",
+})
+
+# Log the validation event
+audit = AuditLog()
+audit.record(result)
+```
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

gateframe-0.1.0/gateframe/__init__.py

@@ -0,0 +1 @@
+

gateframe-0.1.0/gateframe/audit/__init__.py

@@ -0,0 +1 @@
+

gateframe-0.1.0/gateframe/audit/log.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+import structlog
+
+from gateframe.core.contract import ValidationResult
+
+logger = structlog.get_logger()
+
+
+class AuditEntry:
+    __slots__ = (
+        "timestamp",
+        "contract_name",
+        "passed",
+        "rules_applied",
+        "rules_failed",
+        "failures",
+    )
+
+    def __init__(self, result: ValidationResult) -> None:
+        self.timestamp = datetime.now(timezone.utc)
+        self.contract_name = result.contract_name
+        self.passed = result.passed
+        self.rules_applied = result.rules_applied
+        self.rules_failed = result.rules_failed
+        self.failures = [
+            {
+                "rule_name": f.rule_name,
+                "failure_mode": f.failure_mode.value,
+                "message": f.message,
+            }
+            for f in result.failures
+        ]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "timestamp": self.timestamp.isoformat(),
+            "contract_name": self.contract_name,
+            "passed": self.passed,
+            "rules_applied": self.rules_applied,
+            "rules_failed": self.rules_failed,
+            "failures": self.failures,
+        }
+
+
+class AuditLog:
+    def __init__(self) -> None:
+        self._entries: list[AuditEntry] = []
+
+    def record(self, result: ValidationResult) -> None:
+        entry = AuditEntry(result)
+        self._entries.append(entry)
+        logger.info(
+            "validation_event",
+            contract=entry.contract_name,
+            passed=entry.passed,
+            rules_applied=entry.rules_applied,
+            rules_failed=entry.rules_failed,
+        )
+
+    @property
+    def entries(self) -> list[AuditEntry]:
+        return list(self._entries)
+
+    def clear(self) -> None:
+        self._entries.clear()

gateframe-0.1.0/gateframe/core/__init__.py

@@ -0,0 +1 @@
+

gateframe-0.1.0/gateframe/core/contract.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from gateframe.core.failure import FailureResult
+from gateframe.core.rule import Rule
+
+
+class ValidationResult(BaseModel):
+    passed: bool
+    contract_name: str
+    failures: list[FailureResult] = Field(default_factory=list)
+    rules_applied: int
+    rules_failed: int
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+
+    model_config = {"frozen": True}
+
+
+class ValidationContract:
+    def __init__(self, name: str, rules: list[Rule]) -> None:
+        self.name = name
+        self.rules = rules
+
+    def validate(self, output: Any, **context: Any) -> ValidationResult:  # noqa: ANN401
+        failures: list[FailureResult] = []
+
+        for rule in self.rules:
+            result = rule.validate(output, **context)
+            if result is not None:
+                failures.append(result)
+
+        return ValidationResult(
+            passed=len(failures) == 0,
+            contract_name=self.name,
+            failures=failures,
+            rules_applied=len(self.rules),
+            rules_failed=len(failures),
+        )

gateframe-0.1.0/gateframe/core/failure.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class FailureMode(Enum):
+    HARD_FAIL = "hard_fail"
+    SOFT_FAIL = "soft_fail"
+    RETRY = "retry"
+    SILENT_FAIL = "silent_fail"
+
+
+class FailureResult(BaseModel):
+    rule_name: str
+    rule_description: str = ""
+    failure_mode: FailureMode
+    message: str
+    context: dict[str, Any] = Field(default_factory=dict)
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+
+    model_config = {"frozen": True}

gateframe-0.1.0/gateframe/core/rule.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from gateframe.core.failure import FailureResult
+
+
+class Rule(ABC):
+    def __init__(self, name: str, description: str = "") -> None:
+        self.name = name
+        self.description = description
+
+    @abstractmethod
+    def validate(self, output: Any, **context: Any) -> FailureResult | None:  # noqa: ANN401
+        ...

gateframe-0.1.0/gateframe/rules/__init__.py

@@ -0,0 +1 @@
+

gateframe-0.1.0/gateframe/rules/structural.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ValidationError
+
+from gateframe.core.failure import FailureMode, FailureResult
+from gateframe.core.rule import Rule
+
+
+class StructuralRule(Rule):
+    def __init__(
+        self,
+        schema: type[BaseModel],
+        failure_mode: FailureMode = FailureMode.HARD_FAIL,
+        name: str = "",
+        description: str = "",
+    ) -> None:
+        resolved_name = name or f"structural:{schema.__name__}"
+        super().__init__(resolved_name, description)
+        self.schema = schema
+        self.failure_mode = failure_mode
+
+    def validate(self, output: Any, **context: Any) -> FailureResult | None:  # noqa: ANN401
+        if isinstance(output, self.schema):
+            return None
+
+        if isinstance(output, dict):
+            try:
+                self.schema.model_validate(output)
+                return None
+            except ValidationError as exc:
+                return self._build_failure(exc)
+
+        return FailureResult(
+            rule_name=self.name,
+            rule_description=self.description,
+            failure_mode=self.failure_mode,
+            message=(
+                f"{self.name} failed: expected dict or {self.schema.__name__}, "
+                f"got {type(output).__name__}."
+            ),
+            context={"expected_type": self.schema.__name__, "actual_type": type(output).__name__},
+        )
+
+    def _build_failure(self, exc: ValidationError) -> FailureResult:
+        errors = exc.errors()
+        parts = []
+        for err in errors:
+            loc = ".".join(str(segment) for segment in err["loc"])
+            parts.append(f"{loc}: {err['msg']}")
+        detail = "; ".join(parts)
+
+        return FailureResult(
+            rule_name=self.name,
+            rule_description=self.description,
+            failure_mode=self.failure_mode,
+            message=f"{self.name} failed: {detail}.",
+            context={"validation_errors": errors},
+        )

gateframe-0.1.0/gateframe.egg-info/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: gateframe
+Version: 0.1.0
+Summary: Behavioral validation for LLM outputs in production workflows.
+License-Expression: MIT
+Keywords: llm,validation,behavioral,workflow,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: structlog>=23.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# Gateframe
+
+Behavioral validation for LLM outputs. Not schema validation - tools like Instructor and Pydantic AI already handle that. gateframe validates whether an LLM output *behaves correctly* given the context it was generated in, stays within decision boundaries, and fails in ways your system can recover from.
+
+```python
+from pydantic import BaseModel
+from gateframe.core.contract import ValidationContract
+from gateframe.core.failure import FailureMode
+from gateframe.rules.structural import StructuralRule
+
+class TriageOutput(BaseModel):
+    severity: str
+    recommendation: str
+    confidence: float
+
+contract = ValidationContract(
+    name="triage_check",
+    rules=[
+        StructuralRule(schema=TriageOutput),
+    ],
+)
+
+result = contract.validate({
+    "severity": "high",
+    "recommendation": "Escalate to on-call engineer",
+    "confidence": 0.92,
+})
+
+assert result.passed
+```
+
+When validation fails, you get structured failure records - not just a boolean:
+
+```python
+result = contract.validate({"severity": "high"})
+
+assert not result.passed
+for failure in result.failures:
+    print(failure.message)
+    # structural:TriageOutput failed: recommendation: Field required; confidence: Field required.
+```
+
+## Failure modes
+
+gateframe distinguishes four failure modes instead of binary pass/fail:
+
+**HARD_FAIL** - Stop execution, escalate. The output is wrong in a way that cannot be auto-recovered.
+
+```python
+# Missing required fields in a medical triage output
+StructuralRule(schema=TriageOutput, failure_mode=FailureMode.HARD_FAIL)
+```
+
+**SOFT_FAIL** - Flag the output and continue with degraded confidence. Something is off but not critical.
+
+```python
+# Output has all fields but confidence is below threshold
+StructuralRule(schema=TriageOutput, failure_mode=FailureMode.SOFT_FAIL)
+```
+
+**RETRY** - Re-prompt with failure context. The output is fixable by trying again.
+
+```python
+# Malformed JSON that might parse on a second attempt
+StructuralRule(schema=TriageOutput, failure_mode=FailureMode.RETRY)
+```
+
+**SILENT_FAIL** - The most dangerous kind. Output looks valid but violates semantic or boundary rules. gateframe makes these visible instead of letting them pass through.
+
+## When to use gateframe
+
+Use it when:
+- You need to validate LLM outputs beyond schema checks - behavioral contracts, decision boundaries, cross-step propagation
+- You need structured failure records for debugging production incidents
+- You want to distinguish between "retry this", "flag this", and "stop everything"
+
+Don't use it when:
+- You only need schema extraction from LLM outputs (use Instructor or Pydantic AI)
+- You need offline model evaluation or benchmarking (use DeepEval or RAGAS)
+- You need content safety filtering (use a dedicated guardrails tool)
+
+## Installation
+
+```bash
+pip install gateframe
+```
+
+For development:
+
+```bash
+git clone https://github.com/practicalmind-ai/gateframe.git
+cd gateframe
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from pydantic import BaseModel
+from gateframe.core.contract import ValidationContract
+from gateframe.rules.structural import StructuralRule
+from gateframe.audit.log import AuditLog
+
+# Define your expected output schema
+class AgentResponse(BaseModel):
+    action: str
+    reasoning: str
+
+# Create a contract with rules
+contract = ValidationContract(
+    name="agent_response_check",
+    rules=[StructuralRule(schema=AgentResponse)],
+)
+
+# Validate LLM output
+result = contract.validate({
+    "action": "send_email",
+    "reasoning": "User requested a follow-up email to the client.",
+})
+
+# Log the validation event
+audit = AuditLog()
+audit.record(result)
+```
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

gateframe-0.1.0/gateframe.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+gateframe/__init__.py
+gateframe.egg-info/PKG-INFO
+gateframe.egg-info/SOURCES.txt
+gateframe.egg-info/dependency_links.txt
+gateframe.egg-info/requires.txt
+gateframe.egg-info/top_level.txt
+gateframe/audit/__init__.py
+gateframe/audit/log.py
+gateframe/core/__init__.py
+gateframe/core/contract.py
+gateframe/core/failure.py
+gateframe/core/rule.py
+gateframe/rules/__init__.py
+gateframe/rules/structural.py

gateframe-0.1.0/gateframe.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gateframe-0.1.0/gateframe.egg-info/requires.txt

@@ -0,0 +1,7 @@
+pydantic<3.0,>=2.0
+structlog>=23.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+ruff>=0.4.0

gateframe-0.1.0/gateframe.egg-info/top_level.txt

@@ -0,0 +1 @@
+gateframe

gateframe-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gateframe"
+version = "0.1.0"
+description = "Behavioral validation for LLM outputs in production workflows."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["llm", "validation", "behavioral", "workflow", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0,<3.0",
+    "structlog>=23.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.4.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["gateframe*"]
+exclude = ["tests*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

gateframe-0.1.0/setup.cfg

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