Skip to main content
The Ruby gem calls the same compiled Rust core the Python and TypeScript SDKs use, in-process via Ruby’s stdlib 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 one Visiq::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.
Run the tool only when 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 Governor already 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. Set VISIQ_FAIL_MODE=closed (or fail_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:
Fetch it again at least every few seconds, sending the response’s 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 by VISIQ_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 with VISIQ_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.