kyvvu-engine

Runtime policy evaluation for AI agents. The engine checks an intended behaviour against the ordered history of its task, returning allow, warn, or block with the policy outcomes that explain the decision. A behaviour's kind identifies the action being governed, such as a model call, resource access, or decision gate.

It powers the Kyvvu Python client and can also be embedded directly or served over HTTP. The model is described in Runtime Governance for AI Agents: Policies on Paths.

Installation

pip install kyvvu-engine

Most Python agents should install kyvvu for decorators and task management. For a local HTTP server, install the command with uv tool install kyvvu-cli and run kyvvu serve.

Project probe

Run python -m kyvvu_engine.info with the Python interpreter used by your agent to print one JSON object describing its installed Kyvvu environment. probe_version is the output format version (currently 1); interpreter is the interpreter's executable path; distributions lists the names and versions of installed distributions whose names start with kyvvu; and templates lists each kyvvu.templates entry point's name, declaring distribution, and template path. The output contract is the JSON schema shipped in the package as kyvvu_engine/project_probe.schema.json (read it with importlib.resources.files("kyvvu_engine") / "project_probe.schema.json").

Templates

The template system that maps a framework's events to behaviours is not part of the engine. It is the Apache-2.0 kyvvu-templates package, imported as kyvvu_templates. The engine keeps only the KV_TEMPLATE_LOCATION setting, which points an integration at a custom template, and the project probe above, which lists the templates installed integrations declare.

Quickstart

Start with a local policy file. Evaluation needs no account or API key.

1. Offline — no account, no API key, no network

Write a manifest. This is the same format the manifests in Kyvvu/manifests are written in, so anything there runs locally too:

# my-policies.yaml
name: My first policy set
version: "1.0.0"
policies:
  - name: Code execution requires a preceding gate
    rule_type: step_requires_gate
    params:
      target_kinds: ["step.exec"]
    severity: critical
    enforcement_point: step_execution

Point a runner at it and evaluate:

from kyvvu_engine import KyvvuBlockedError, KyvvuRunner
from kyvvu_engine import Behavior, EvalContext, ActionKind

runner = KyvvuRunner(policy_file="my-policies.yaml", log_location="none")

# Load now, and check what is actually being enforced before trusting any
# verdict. Policies otherwise load lazily on the first evaluate(), so a
# load_report() read before that reports `unavailable` — nothing has been
# asked to load yet.
status = runner.ensure_policies()
print(status.load_state.value, status.policies_offered, status.policy_count)
# enforcing 1 1

ctx = EvalContext(
    agent_id="local-agent",
    task_id="task-1",
    # Declare the agent's tools. Not needed by the policy above, but the
    # OWASP set's allowlist policy reads this field (NOT the agent payload's
    # declared_tools) and fails closed: leave it unset there and every
    # step.resource / step.exec / step.credential blocks on "Tool calls must
    # be in the declared allowlist".
    agent_allowed_tools=["run_script"],
)

# A task is opened by recording its task.start; every other write needs it.
runner.record(Behavior(
    agent_id="local-agent",
    task_id="task-1",
    kind=ActionKind.task_start,
    step_name="task.start",
))

intended = Behavior(
    agent_id="local-agent",
    task_id="task-1",
    kind=ActionKind.step_exec,
    step_name="run_script",
    input={"code": "rm -rf /"},
)

try:
    runner.evaluate(intended, ctx)
except KyvvuBlockedError as exc:
    print(exc)          # Step 'run_script' blocked (risk_score=1.00): …
    # The runner has already recorded the blocked step (exc.result.recorded_seq);
    # do not record it again.

2. Platform-connected

Follow the first-agent guide for agent registration and credentials, or the REST integration guide for a non-Python harness. To expose local policies over HTTP, see kyvvu serve.

Documentation

• Architecture and policies on paths
• Behaviour kinds and properties
• Task lifecycle and history
• Policy rules and compound policies
• Runtime configuration
• Trace export and provenance
• Policy diagnostics
• Interface stability
• Changelog
• Report an issue

The supported Python interface is the names in kyvvu_engine.__all__. Import them from kyvvu_engine; submodule paths are internal. Breaking that interface requires a major version under the stability policy linked above.

Licence

The engine is source-available under the Business Source License 1.1 (BSL 1.1). Free use covers development, testing, research, evaluation, and personal non-commercial purposes. Production use requires a commercial subscription or separate agreement. Each release converts to Apache-2.0 four years after publication. See licensing and contact licensing@kyvvu.com for commercial terms.