The engine¶

kyvvu-engine is the part of Kyvvu that makes a decision. Before an agent acts, the engine evaluates the intended behaviour against a policy set and the history of the task so far, and returns allow, warn or block with the policy outcomes that explain it. It runs in the agent's own process, or beside it as kyvvu serve. What it promises is on The engine contract.

Why every integration includes it¶

Every way of connecting an agent to Kyvvu evaluates its policies locally, with this engine, so a block happens before the action rather than in a report after it:

The platform does not evaluate on an agent's behalf: it serves policies and stores what agents record. The same engine version therefore makes the same decision whichever integration called it.

What is in it¶

• The policy engine: the built-in rules, policy loading and validation, and evaluation against the task's history.
• The runner, KyvvuRunner: one agent's policy source, its open tasks, and the sinks its records and incidents go to.
• The behaviour vocabulary: the AAG action kinds and verbs, and the Behavior schema every integration maps its events onto.
• The hash chain that links a task's records, computed on the client and verified by the platform.
• kyvvu serve's HTTP server, in the serve extra, for agents that are not written in Python; see the kyvvu serve HTTP API.

Its settings are on Engine settings, and its Python interface is the engine Python API.

Templates¶

The template system — loading a behaviour template, matching events against its rules, and merging templates — is not in the engine. It is the Apache-2.0 kyvvu-templates package, imported as kyvvu_templates; see Write a template and its Python API. The engine keeps only two things about templates: the KV_TEMPLATE_LOCATION setting, which points an integration at a custom template, and the project probe, python -m kyvvu_engine.info, which lists the templates installed integrations declare.

Install¶

Install the engine together with kyvvu-baseline, the frozen 15-policy baseline. The engine ships no policies of its own, so kyvvu-engine alone has nothing to enforce offline:

pip install kyvvu-engine kyvvu-baseline

Install the engine on its own only to embed it directly. To instrument a Python agent, install the Python client instead; it brings both packages with it.

Licence¶

The engine is source-available under the Business Source License 1.1 (BSL 1.1). Development, testing, research, evaluation and personal non-commercial use are free; production use needs a Kyvvu commercial subscription. Each release converts to Apache License 2.0 four years after it is published. The baseline policies and the integrations are Apache 2.0, but evaluating them runs the engine, so its terms apply. See Licensing.

Offline and with the platform¶

Offline, the engine reads its policies from a file, or from the baseline, and needs no account, API key or network. Records go to standard output, a file or an OpenTelemetry endpoint. This is what kyvvu try runs.

With the platform, a runner configured with an API URL, an API key and an agent key registers the agent, fetches the policies assigned to it, refreshes them in the background, and sends its records and incidents to the platform. Evaluation still happens in the agent's process: if the platform stops answering, the engine keeps enforcing the last set it fetched.