Fiddle FFI — zero runtime gem dependencies.
One core, many languages; every decision is local.
Scope: every decision is made in-process, and
Visiq::Governor keeps the
agent’s rules current by fetching them from the control plane itself. For
human-in-the-loop approvals and audit streaming this gem is a
local-decision layer only: an approval_required verdict is returned to your
code, and audit events are yours to send. The Python and TypeScript SDKs carry both.Install
The gem bundles the platform-matching compiled core, so there is no separate native install.Govern a tool call
Create oneVisiq::Governor per agent and keep it for the life of the process.
It fetches the agent’s rule bundle from the control plane, fetches it again once
it is more than 5 seconds old, and decides each call in-process against it. A
rule change, or putting the agent in Agent Jail,
therefore reaches the agent’s next call without any code of yours.
decision["allowed"] is true. On a mask verdict,
apply decision["action"]["argRedactionRules"] to the args first.
Each option you leave out is read from the environment:
Set the endpoint only for an on-premises or sovereign deployment.
When the control plane cannot be reached
- A failed or slow fetch (2.5 second timeout) keeps the rules the
Governoralready holds, however old they are. An agent in Agent Jail stays blocked until the control plane serves it a normal bundle again. - Before the first successful fetch, or with no API key configured, each call is
permitted and a
[VisIQ] FAIL-OPEN (no-bundle): ...line goes to stderr. SetVISIQ_FAIL_MODE=closed(orfail_mode: "closed") to deny those calls instead.
governor.bundle returns the bundle in use, frozen, or nil before the first
successful fetch.
Govern a retrieval
governor.gate_retrieval(resource_metadata:) decides one retrieval. Read
decision["retrieval"]["action"]: drop the content on deny or escalate, and
on redact apply decision["retrieval"]["redactionRules"], before the content
reaches the model.
If you fetch the bundle yourself
Visiq.gate_action(bundle, tool_name:, args:, agent_id:) and
Visiq.gate_retrieval(bundle, resource_metadata:, agent_id:) decide against a
bundle you pass in, and make no network calls. Fetch the bundle over the
rules API and parse it into a Hash:
ETag back as
If-None-Match: a kill switch such as Agent Jail reaches the agent only through
a fresh bundle.
Fail mode
A failure inside the SDK itself (the compiled core cannot load, or an FFI error) is routed byVISIQ_FAIL_MODE: open (default) returns a permit decision
plus a loud stderr line, so a VisIQ packaging problem never stops the agent;
closed blocks instead: a core failure raises, and a Governor that has no
rules yet returns a deny. A rule’s deny, including Agent Jail, always
blocks, whatever the fail mode.
Override the core library
The gem loads its bundled core. Point it at a specific library withVISIQ_CORE_LIB (an absolute path), matching the Go and Java bindings.
Next steps
Java Reference
The Java binding —
gateAction over the same core.Python Reference
The full Python harness — Governor, gates, and audit streaming.