Java SDK

Prerequisites

Set SILMARIL_API_KEY and SILMARIL_API_URL from your deployment access.

Install

Gradle

dependencies {
    implementation("com.silmaril.security:silmaril-security-sdk:0.7.0")
}

Classify your first request

Create one client per protected system and reuse it. Label each call with the boundary it checks.

import dev.silmaril.security.BlockResult;
import dev.silmaril.security.ClassifyOptions;
import dev.silmaril.security.Firewall;
import dev.silmaril.security.FirewallBlockedException;
import dev.silmaril.security.HookLabel;

public class FirstClassification {
    public static void main(String[] args) throws Exception {
        Firewall fw = Firewall.builder()
            .apiKey(System.getenv("SILMARIL_API_KEY"))
            .apiUrl(System.getenv("SILMARIL_API_URL"))
            .build();

        try {
            BlockResult result = fw.classify(
                "Summarize this release note.",
                ClassifyOptions.builder()
                    .hook(HookLabel.USER_INPUT)
                    .build()
            );
            System.out.println("prediction=" + result.prediction());
        } catch (FirewallBlockedException blocked) {
            System.err.println("block score=" + blocked.score() + " threshold=" + blocked.threshold());
            return;
        } catch (Exception failure) {
            throw failure;
        }
    }
}

For tool output, pass the tool name as well and keep the returned verdict:

BlockResult toolVerdict = fw.classify(
    toolOutput,
    ClassifyOptions.builder()
        .hook(HookLabel.TOOL_RESPONSE)
        .toolName("read_file")
        .build()
);
System.out.println("prediction=" + toolVerdict.prediction());

Read toolVerdict before the application consumes that tool output. In effective Block mode, a malicious prediction or an explicit governance block throws FirewallBlockedException instead of returning.

Expected result

A benign request prints prediction=BENIGN. prediction is the authoritative BENIGN or MALICIOUS verdict. score() and threshold() are diagnostics. Thresholds are fixed values controlled by the tenant. Effective Block stops the event when prediction is MALICIOUS or the governance action is block, including when prediction is BENIGN. That stop throws FirewallBlockedException, which carries result(), score(), and threshold(). Warn reports the would-block finding and continues. Shadow records it and continues. Both return the verdict. They are observational and are not enforced automatically. The deployment sets the default mode. A client or per-call mode(...) override is opt-in. An API, network, timeout, or cancellation failure means the call produced no verdict. It is not a block. Decide whether that boundary fails open or closed. Outcome categories are in the outcome taxonomy.

Governance context

The API accepts typed agent and resource context on an individual classify() call and on each batch item. Follow the same concepts as the other SDKs: agent, resource.kind, and resource.id.

import dev.silmaril.security.GovernanceContext;
import dev.silmaril.security.GovernanceResource;
import dev.silmaril.security.GovernanceDecision;

GovernanceContext context = GovernanceContext.builder()
    .agent("research-agent")
    .resource(GovernanceResource.builder()
        .kind("tool")
        .id("search")
        .build())
    .build();

BlockResult result = fw.classify(
    "Search for the latest release notes",
    ClassifyOptions.builder()
        .hook(HookLabel.TOOL_CALL)
        .toolName("search")
        .governance(context)
        .build()
);

GovernanceDecision decision = result.governance();
if (decision != null) {
    System.out.println(decision.action() + " " + decision.policyVersion() + " " + decision.ruleId());
}

The optional governance decision contains the action, policy version, and rule ID. Older responses can omit it. Check that the decision is present before reading action(). A malicious prediction or an explicit governance block stops the event only in effective Block mode. In Warn, report the would-block finding and continue. In Shadow, record it and continue.

Conversation metadata

A conversationId is caller-owned metadata. Pass it on each call with the option ClassifyOptions.builder().metadata(Map.of("conversationId", conversationId)):

import java.util.Map;

ClassifyOptions options = ClassifyOptions.builder()
    .hook(HookLabel.USER_INPUT)
    .metadata(Map.of("conversationId", conversationId))
    .build();

Current Cascade conversation-aware checks require ordered individual classify() calls that reuse that id. Wait for and handle every verdict or error before consuming that event or sending the next event for the same id.

Concurrent requests

Concurrent calls are for independent events or different conversations. For a shared conversationId, wait for and handle every verdict or error before sending the next event for that id.

Batch calls and conversation history

classifyBatch() accepts one metadata context per item, including conversationId, and one optional governance context per item. Current Cascade batch classification preserves that per-item metadata and neither reads nor updates conversation history. The same id does not connect batch items into a sequence or attach them to previously cached history. Prefer ordered individual classify() calls for conversation-aware checks. Keep every returned verdict, including a Warn or Shadow tool-output result, and inspect its prediction and optional governance action before the event is consumed or the next event for that conversation is sent. Use the effective mode for a malicious prediction or an explicit governance block: Block stops the event; Warn reports the would-block finding and continues; Shadow records it and continues. Inspecting a Warn or Shadow verdict does not enforce it. See the outcome taxonomy for verdict categories.

Modes

Mode	Malicious prediction or governance action `block`
`FirewallMode.BLOCK`	Stop the event. `classify()` throws `FirewallBlockedException`.
`FirewallMode.WARN`	Report the would-block finding and continue. The call returns the verdict.
`FirewallMode.SHADOW`	Record the would-block finding and continue. The call returns the verdict.

Warn and Shadow return verdicts. They are not enforced automatically. The deployment sets the default. Set an explicit mode on the client or on one call only when that override is intentional:

import dev.silmaril.security.FirewallMode;

Firewall fw = Firewall.builder()
    .apiKey(System.getenv("SILMARIL_API_KEY"))
    .apiUrl(System.getenv("SILMARIL_API_URL"))
    .mode(FirewallMode.SHADOW)
    .build();

BlockResult verdict = fw.classify(
    text,
    ClassifyOptions.builder()
        .hook(HookLabel.TOOL_RESPONSE)
        .toolName("read_file")
        .mode(FirewallMode.BLOCK)
        .build()
);

Keep verdict when the call returns. The per-call mode is Block, so that call enforces. shadowMode(true) is legacy shorthand for mode(FirewallMode.SHADOW), and shadowMode(false) is legacy shorthand for an enforcing call. Prefer FirewallMode.

Errors

An enforced block throws FirewallBlockedException. The exception carries the full result(), plus score() and threshold().

try {
    BlockResult result = fw.classify(userInput, options);
    System.out.println("prediction=" + result.prediction());
} catch (FirewallBlockedException blocked) {
    BlockResult verdict = blocked.result();
    System.err.println(
        "blocked prediction=" + verdict.prediction()
            + " score=" + blocked.score()
            + " threshold=" + blocked.threshold()
    );
    return;
} catch (Exception failure) {
    throw failure;
}

options is the ClassifyOptions value for that boundary. Any other failure, including an API error, network error, timeout, or cancellation, means that call produced no verdict. It is not a block. Outcome categories are in the outcome taxonomy.

Start

Concepts

SDKs

AI gateways

Integrations

Deployment

MacOS

Prerequisites

Install

Classify your first request

Expected result

Governance context

Conversation metadata

Concurrent requests

Batch calls and conversation history

Modes

Errors

​Prerequisites

​Install

​Classify your first request

​Expected result

​Governance context

​Conversation metadata

​Concurrent requests

​Batch calls and conversation history

​Modes

​Errors

Prerequisites

Install

Classify your first request

Expected result

Governance context

Conversation metadata

Concurrent requests

Batch calls and conversation history

Modes

Errors