Java SDK Reference

The Java binding calls the same compiled Rust core the Python and TypeScript SDKs use, in-process via the Foreign Function & Memory API (Panama, finalized in JDK 22) — no JNI shim. One core, many languages; every decision is local.

Scope: local-decision layer only — bundle auto-refresh, HITL and audit streaming are the Governor harness (Python/TypeScript only). This binding makes one thing fast and local: the policy DECISION. You fetch the rule bundle and stream audit yourself.

Install

The jar bundles the platform-matching compiled core (extracted at load time), so there is no separate native install.

<dependency>
  <groupId>com.visiqlabs</groupId>
  <artifactId>visiq-sdk</artifactId>
  <version>0.1.1</version>
</dependency>

Requires JDK 22+, run with --enable-native-access=ALL-UNNAMED so the FFM downcall to the core is permitted.

Acquire a bundle

Every decision is made against a rule bundle you fetch from the control plane and parse. Fetch it over the rules API:

curl -H "Authorization: Bearer $VISIQ_API_KEY" \
  "$VISIQ_ENDPOINT/rules/bundle?agent_id=support-bot"

VISIQ_ENDPOINT defaults to https://api.visiqlabs.com; set it only for onprem. Parse the returned JSON into a Jackson JsonNode (bundle) and pass it in.

Govern a tool call

Visiq.gateAction(bundle, toolName, args, agentId) decides one tool/action call. Inspect decision.get("allowed"); on a mask verdict apply decision.get("action").get("argRedactionRules") to the args first.

// guide:begin
JsonNode decision = Visiq.gateAction(bundle, "wire_transfer", args, "sdk-agent");
System.out.println("allowed=" + decision.get("allowed").asBoolean());
// guide:end

This exact snippet is executed as a proof (GuideExampleTest) against a bundle copied verbatim from the oracle-stamped conformance corpus: the deny fixture blocks (allowed=false), the permit fixture passes (allowed=true).

Govern a retrieval

Visiq.gateRetrieval(bundle, resourceMetadata, agentId) decides one retrieval. Inspect decision.get("retrieval").get("action") — drop on deny/escalate, redact via retrieval.get("redactionRules") — before content reaches the model.

JsonNode decision = Visiq.gateRetrieval(bundle, metadata, "sdk-agent");
System.out.println("action=" + decision.get("retrieval").get("action").asText());

Fail mode

A HARNESS-internal failure — the native core can’t load, or visiq_evaluate returns NULL/throws — is routed by VISIQ_FAIL_MODE (owner G001 rescope): open (default) returns a permit-equivalent decision plus a loud stderr report so a VisIQ packaging bug never disrupts the agent; closed throws a fail-closed exception. A real rule deny always blocks regardless of fail mode.

VISIQ_FAIL_MODE=closed   # strict: a core-load/FFI failure denies instead of proceeding

Override the core library

The jar extracts its bundled core to a temp file. Point it at a specific library with VISIQ_CORE_LIB (an absolute path), matching the Go and Ruby bindings.

VISIQ_CORE_LIB=/opt/visiq/libvisiq_core.so

Next steps

Ruby Reference

The published Ruby gem — gate_action over the same core.

Python Reference

The full Python harness — Governor, gates, and audit streaming.

Quickstart

Action Governance

Retrieval Governance

Delegation Governance

Unified Rules

Audit Trail

Discovery

Connectors

API Examples

Platform Automation

Partners

Reference

API Reference

Java SDK Reference

Install

Acquire a bundle

Govern a tool call

Govern a retrieval

Fail mode

Override the core library

Next steps

Ruby Reference

Python Reference

​Install

​Acquire a bundle

​Govern a tool call

​Govern a retrieval

​Fail mode

​Override the core library

​Next steps

Ruby Reference

Python Reference

Install

Acquire a bundle

Govern a tool call

Govern a retrieval

Fail mode

Override the core library

Next steps