kyvvu-engine 0.3.0__py3-none-any.whl

kyvvu_engine/__init__.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: BUSL-1.1
+# Copyright 2026 Kyvvu B.V.
+
+"""kyvvu-engine — standalone policy evaluation engine for AI governance.
+
+Public API
+----------
+Core evaluation (zero-I/O)::
+
+    from kyvvu_engine import PolicyEngine
+
+I/O wrapper (policy fetch + batch logging)::
+
+    from kyvvu_engine import KyvvuRunner, KyvvuSettings
+
+Exceptions::
+
+    from kyvvu_engine import KyvvuBlockedError, KyvvuConfigError
+
+Everything else (:mod:`~kyvvu_engine.schemas`, :mod:`~kyvvu_engine.rules`,
+etc.) is importable for advanced use but not part of the stable public interface.
+
+Note
+----
+Template mapping (framework events → v0.05 behaviors) has moved to the
+``kyvvu`` SDK package::
+
+    from kyvvu.templates import load_builtin, load_template, BehaviorTemplate
+"""
+
+from kyvvu_engine.__version__ import __version__
+from kyvvu_engine.aggregation import (
+    aggregate_max,
+    aggregate_mean,
+    aggregate_weighted_sum,
+)
+from kyvvu_engine.engine import PolicyEngine
+from kyvvu_engine.io.exceptions import KyvvuBlockedError, KyvvuConfigError
+from kyvvu_engine.io.runner import KyvvuRunner
+from kyvvu_engine.io.settings import KyvvuSettings
+from kyvvu_engine.logging import setup_logging
+from kyvvu_engine.rules._registry import PolicyRule
+from kyvvu_engine.schemas import PolicyStatus
+
+__all__ = [
+    "PolicyEngine",
+    "KyvvuRunner",
+    "KyvvuSettings",
+    "KyvvuBlockedError",
+    "KyvvuConfigError",
+    "PolicyRule",
+    "PolicyStatus",
+    "aggregate_max",
+    "aggregate_mean",
+    "aggregate_weighted_sum",
+    "setup_logging",
+    "__version__",
+]

kyvvu_engine/__version__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BUSL-1.1
+# Copyright 2026 Kyvvu B.V.
+
+__version__ = "0.3.0"

kyvvu_engine/_cli.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: BUSL-1.1
+# Copyright 2026 Kyvvu B.V.
+
+"""Entry point for the ``kyvvu-serve`` CLI.
+
+Starts a local HTTP server wrapping :class:`~kyvvu_engine.engine.PolicyEngine`
+so non-Python harnesses can evaluate policies via REST.
+
+Requires the ``[serve]`` extra::
+
+    pip install "kyvvu-engine[serve]"
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> None:
+    """Parse CLI args and start the kyvvu-serve uvicorn server.
+
+    Reads configuration from CLI flags (``--agent-key``, ``--api-url``,
+    ``--api-key``) and falls back to ``KV_*`` environment variables for
+    unset values.  Requires the ``[serve]`` extra for uvicorn/fastapi.
+    """
+    parser = argparse.ArgumentParser(
+        prog="kyvvu-serve",
+        description="Local policy evaluation server for kyvvu-engine",
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="Bind address (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=8090, help="Bind port (default: 8090)")
+    parser.add_argument("--agent-key", default=None, help="Agent key for policy fetch")
+    parser.add_argument("--api-url", default=None, help="Kyvvu platform API URL")
+    parser.add_argument("--api-key", default=None, help="Bearer API key")
+    args = parser.parse_args()
+
+    try:
+        import uvicorn
+    except ImportError:
+        print(
+            "kyvvu-serve requires the [serve] extra.\n"
+            'Install with: pip install "kyvvu-engine[serve]"',
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    from kyvvu_engine.serve.app import create_app
+
+    app = create_app(
+        agent_key=args.agent_key,
+        api_url=args.api_url,
+        api_key=args.api_key,
+    )
+    uvicorn.run(app, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

kyvvu_engine/aggregation.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: BUSL-1.1
+# Copyright 2026 Kyvvu B.V.
+
+"""Score aggregation strategies for kyvvu-engine.
+
+Given a list of per-policy outcomes, these functions compute an aggregate
+risk score and derive the recommended :class:`~kyvvu_engine.schemas.Action`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from kyvvu_engine.schemas import Action, EvalResult, PolicyResult
+
+logger = logging.getLogger(__name__)
+
+# Normalised weight per severity level.  ``critical`` maps to the maximum
+# score of 1.0 so that a single critical violation always triggers ``block``.
+SEVERITY_WEIGHTS: dict[str, float] = {
+    "low": 0.25,
+    "medium": 0.50,
+    "high": 0.75,
+    "critical": 1.0,
+}
+
+
+def _score_to_action(score: float) -> Action:
+    """Map a normalised risk score to a recommended :class:`Action`.
+
+    Args:
+        score: Risk score in ``[0.0, 1.0]``.
+
+    Returns:
+        :attr:`Action.allow` when score is ``0.0``,
+        :attr:`Action.block` when score is ``>= 1.0``,
+        :attr:`Action.warn` for any value in between.
+    """
+    if score == 0.0:
+        return Action.allow
+    if score >= 1.0:
+        return Action.block
+    return Action.warn
+
+
+def aggregate_max(results: list[PolicyResult]) -> EvalResult:
+    """Aggregate by taking the maximum severity among all violations.
+
+    Action thresholds:
+    - ``risk_score == 0.0`` → :attr:`Action.allow`
+    - ``0.0 < risk_score < 1.0`` → :attr:`Action.warn`
+    - ``risk_score == 1.0`` → :attr:`Action.block`
+
+    Args:
+        results: Per-policy evaluation outcomes.
+
+    Returns:
+        :class:`EvalResult` with ``risk_score`` and ``action`` from worst violation.
+    """
+    violations = [r for r in results if r.violated]
+    if not violations:
+        return EvalResult(risk_score=0.0, action=Action.allow, policies=results)
+    max_score = max(SEVERITY_WEIGHTS.get(v.severity, 0.0) for v in violations)
+    return EvalResult(risk_score=max_score, action=_score_to_action(max_score), policies=results)
+
+
+def aggregate_mean(results: list[PolicyResult]) -> EvalResult:
+    """Aggregate by computing the mean severity across all violations.
+
+    Args:
+        results: Per-policy evaluation outcomes.
+
+    Returns:
+        :class:`EvalResult` with mean risk score.
+    """
+    violations = [r for r in results if r.violated]
+    if not violations:
+        return EvalResult(risk_score=0.0, action=Action.allow, policies=results)
+    mean_score = sum(SEVERITY_WEIGHTS.get(v.severity, 0.0) for v in violations) / len(violations)
+    return EvalResult(risk_score=mean_score, action=_score_to_action(mean_score), policies=results)
+
+
+def aggregate_weighted_sum(
+    results: list[PolicyResult], weights: dict[int | None, float]
+) -> EvalResult:
+    """Aggregate using caller-supplied per-policy weights.
+
+    Args:
+        results: Per-policy evaluation outcomes.
+        weights: Dict mapping policy_id to a numeric weight.
+
+    Returns:
+        :class:`EvalResult` with weighted sum capped at 1.0.
+    """
+    violations = [r for r in results if r.violated]
+    if not violations:
+        return EvalResult(risk_score=0.0, action=Action.allow, policies=results)
+    total: float = sum(
+        weights.get(v.policy_id, SEVERITY_WEIGHTS.get(v.severity, 0.0))
+        for v in violations
+    )
+    score = min(total, 1.0)
+    return EvalResult(risk_score=score, action=_score_to_action(score), policies=results)