feat: add integrations, audit exporters, and CLI

Author: practicalmind-dev

gateframe/audit/exporters.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+if TYPE_CHECKING:
+    from gateframe.audit.log import AuditEntry
+
+logger = structlog.get_logger()
+
+
+class AuditExporter(ABC):
+    @abstractmethod
+    def export(self, entry: AuditEntry) -> None: ...
+
+    @abstractmethod
+    def flush(self) -> None: ...
+
+    def shutdown(self) -> None:  # noqa: B027
+        pass
+
+
+class JsonFileExporter(AuditExporter):
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+        self._handle = open(self._path, "a")  # noqa: SIM115
+
+    def export(self, entry: AuditEntry) -> None:
+        line = json.dumps(entry.to_dict(), default=str)
+        self._handle.write(line + "\n")
+
+    def flush(self) -> None:
+        self._handle.flush()
+
+    def shutdown(self) -> None:
+        self._handle.close()
+
+
+def _require_opentelemetry() -> None:
+    try:
+        import opentelemetry  # noqa: F401
+    except ImportError:
+        raise ImportError(
+            "opentelemetry is required for OtlpExporter. "
+            "Install it with: pip install gateframe[otlp]"
+        ) from None
+
+
+class OtlpExporter(AuditExporter):
+    def __init__(
+        self,
+        endpoint: str = "http://localhost:4317",
+        *,
+        insecure: bool = True,
+        service_name: str = "gateframe",
+    ) -> None:
+        _require_opentelemetry()
+
+        from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
+        from opentelemetry.sdk._logs import LoggerProvider
+        from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+        from opentelemetry.sdk.resources import Resource
+
+        resource = Resource.create({"service.name": service_name})
+        self._provider = LoggerProvider(resource=resource)
+        exporter = OTLPLogExporter(endpoint=endpoint, insecure=insecure)
+        self._provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
+        self._logger = self._provider.get_logger("gateframe.audit")
+
+    def export(self, entry: AuditEntry) -> None:
+        from opentelemetry.sdk._logs import LogRecord
+
+        severity = self._resolve_severity(entry)
+        attributes: dict[str, Any] = {
+            "contract_name": entry.contract_name,
+            "passed": entry.passed,
+            "rules_applied": entry.rules_applied,
+            "rules_failed": entry.rules_failed,
+        }
+        if entry.workflow_id is not None:
+            attributes["workflow_id"] = entry.workflow_id
+        if entry.confidence is not None:
+            attributes["confidence"] = entry.confidence
+
+        record = LogRecord(
+            body=json.dumps(entry.to_dict(), default=str),
+            severity_number=severity,
+            attributes=attributes,
+        )
+        self._logger.emit(record)
+
+    def flush(self) -> None:
+        self._provider.force_flush()
+
+    def shutdown(self) -> None:
+        self._provider.shutdown()
+
+    @staticmethod
+    def _resolve_severity(entry: AuditEntry) -> int:
+        import logging
+
+        has_hard = any(f.get("failure_mode") == "hard_fail" for f in entry.failures)
+        has_soft = any(f.get("failure_mode") == "soft_fail" for f in entry.failures)
+        if has_hard:
+            return logging.ERROR
+        if has_soft:
+            return logging.WARNING
+        return logging.INFO

gateframe/audit/log.py

@@ -8,6 +8,7 @@
 from gateframe.core.contract import ValidationResult
 
 if TYPE_CHECKING:
+    from gateframe.audit.exporters import AuditExporter
     from gateframe.core.context import WorkflowContext
 
 logger = structlog.get_logger()
@@ -62,8 +63,12 @@ def to_dict(self) -> dict[str, Any]:
 
 
 class AuditLog:
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        exporters: list[AuditExporter] | None = None,
+    ) -> None:
         self._entries: list[AuditEntry] = []
+        self._exporters: list[AuditExporter] = exporters or []
 
     def record(
         self,
@@ -82,10 +87,20 @@ def record(
             log_kwargs["workflow_id"] = entry.workflow_id
             log_kwargs["confidence"] = entry.confidence
         logger.info("validation_event", **log_kwargs)
+        for exporter in self._exporters:
+            exporter.export(entry)
 
     @property
     def entries(self) -> list[AuditEntry]:
         return list(self._entries)
 
     def clear(self) -> None:
         self._entries.clear()
+
+    def flush(self) -> None:
+        for exporter in self._exporters:
+            exporter.flush()
+
+    def shutdown(self) -> None:
+        for exporter in self._exporters:
+            exporter.shutdown()

gateframe/cli/__init__.py

@@ -0,0 +1 @@
+

gateframe/cli/inspect.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Any
+
+from gateframe.core.contract import ValidationContract
+
+
+def run_inspect(file_path: str) -> None:
+    path = Path(file_path)
+    if not path.exists():
+        print(f"Error: file not found: {path}")
+        sys.exit(1)
+    if path.suffix != ".py":
+        print(f"Error: not a Python file: {path}")
+        sys.exit(1)
+
+    module = _import_file(path)
+    contracts = _find_contracts(module)
+
+    if not contracts:
+        print(f"No ValidationContract instances found in {path}")
+        sys.exit(0)
+
+    print(f"\nFound {len(contracts)} contract(s) in {path.name}")
+    for var_name, contract in contracts:
+        _print_contract(var_name, contract)
+
+
+def _import_file(path: Path) -> Any:  # noqa: ANN401 -- returns module
+    parent = str(path.parent.resolve())
+    if parent not in sys.path:
+        sys.path.insert(0, parent)
+
+    spec = importlib.util.spec_from_file_location(path.stem, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot load module from {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _find_contracts(module: Any) -> list[tuple[str, ValidationContract]]:  # noqa: ANN401
+    results = []
+    for attr_name in dir(module):
+        if attr_name.startswith("_"):
+            continue
+        obj = getattr(module, attr_name)
+        if isinstance(obj, ValidationContract):
+            results.append((attr_name, obj))
+    return results
+
+
+def _print_contract(var_name: str, contract: ValidationContract) -> None:
+    print(f"\n{'=' * 60}")
+    print(f"Contract: {contract.name}  (variable: {var_name})")
+    print(f"{'=' * 60}")
+    print(f"  Rules ({len(contract.rules)}):")
+    for i, rule in enumerate(contract.rules):
+        rule_type = type(rule).__name__
+        print(f"    [{i}] {rule_type}: {rule.name}")
+        if rule.description:
+            print(f"        {rule.description}")
+        if hasattr(rule, "schema"):
+            print(f"        schema: {rule.schema.__name__}")
+        if hasattr(rule, "failure_mode"):
+            print(f"        failure_mode: {rule.failure_mode.value}")
+    if contract.on_hard_fail:
+        print(f"  on_hard_fail: {contract.on_hard_fail.value}")
+    if contract.on_soft_fail:
+        print(f"  on_soft_fail: {contract.on_soft_fail.value}")

gateframe/cli/main.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def cli() -> None:
+    parser = argparse.ArgumentParser(prog="gateframe", description="gateframe CLI")
+    subparsers = parser.add_subparsers(dest="command")
+
+    inspect_parser = subparsers.add_parser("inspect", help="Introspect a contract file")
+    inspect_parser.add_argument("contract_file", help="Path to a .py file containing contracts")
+
+    replay_parser = subparsers.add_parser("replay", help="Replay an audit log")
+    replay_parser.add_argument("audit_file", help="Path to a JSON/JSONL audit log file")
+
+    args = parser.parse_args()
+
+    if args.command == "inspect":
+        from gateframe.cli.inspect import run_inspect
+
+        run_inspect(args.contract_file)
+    elif args.command == "replay":
+        from gateframe.cli.replay import run_replay
+
+        run_replay(args.audit_file)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

gateframe/cli/replay.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger()
+
+
+def run_replay(file_path: str) -> None:
+    path = Path(file_path)
+    if not path.exists():
+        print(f"Error: file not found: {path}")
+        sys.exit(1)
+
+    entries = _load_entries(path)
+    if not entries:
+        print("No entries found in audit log.")
+        sys.exit(0)
+
+    _print_summary(entries)
+    for i, entry in enumerate(entries):
+        _print_entry(i, entry)
+
+
+def _load_entries(path: Path) -> list[dict[str, Any]]:
+    text = path.read_text()
+
+    # Try JSON array first
+    try:
+        data = json.loads(text)
+        if isinstance(data, list):
+            return data
+        return [data]
+    except json.JSONDecodeError:
+        pass
+
+    # Try JSON Lines
+    entries: list[dict[str, Any]] = []
+    for line_num, line in enumerate(text.splitlines(), 1):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entries.append(json.loads(line))
+        except json.JSONDecodeError:
+            logger.warning("skipping_invalid_line", line_number=line_num)
+    return entries
+
+
+def _print_summary(entries: list[dict[str, Any]]) -> None:
+    total = len(entries)
+    passed = sum(1 for e in entries if e.get("passed"))
+    failed = total - passed
+    print(f"\nAudit Log: {total} entries ({passed} passed, {failed} failed)")
+    print("=" * 60)
+
+
+def _print_entry(index: int, entry: dict[str, Any]) -> None:
+    status = "PASS" if entry.get("passed") else "FAIL"
+    contract = entry.get("contract_name", "?")
+    print(f"\n  [{index}] {contract} -- {status}")
+    print(f"      timestamp: {entry.get('timestamp', '?')}")
+    print(
+        f"      rules: {entry.get('rules_applied', '?')} applied, "
+        f"{entry.get('rules_failed', '?')} failed"
+    )
+    if entry.get("workflow_id"):
+        print(f"      workflow: {entry['workflow_id']}, confidence: {entry.get('confidence', '?')}")
+    for failure in entry.get("failures", []):
+        mode = failure.get("failure_mode", "?")
+        name = failure.get("rule_name", "?")
+        msg = failure.get("message", "?")
+        print(f"      FAILURE: [{mode}] {name}: {msg}")

gateframe/integrations/__init__.py

@@ -0,0 +1 @@
+