> ## Documentation Index
> Fetch the complete documentation index at: https://silmaril.security/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK

> Java 0.7 guide for classifying user input and tool output and handling block verdicts.

## Prerequisites

Set `SILMARIL_API_KEY` and `SILMARIL_API_URL` from your [deployment access](https://silmaril.security/docs/start/access.md).

Confirm Java SDK availability, artifact repository, and compatible Java runtime with Silmaril before adding the dependency or running these examples.

## Install

Add the dependency to your application's `build.gradle.kts`.

```kotlin Gradle theme={"theme":"github-light-default"}
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.

Save this example as `src/main/java/FirstClassification.java` in your Gradle application.

```java theme={"theme":"github-light-default"}
import dev.silmaril.security.BlockResult;
import dev.silmaril.security.ClassifyOptions;
import dev.silmaril.security.Firewall;
import dev.silmaril.security.FirewallBlockedException;
import dev.silmaril.security.FirewallMode;
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"))
            .mode(FirewallMode.BLOCK)
            .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:

```java theme={"theme":"github-light-default"}
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.

See [confidence scores](https://silmaril.security/docs/guides/enforcement.md#confidence-scores) for score meaning and threshold behavior.

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. This example chooses Block explicitly. Choose an explicit mode for each client, and use per-call `mode(...)` only as an intentional override.

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](https://silmaril.security/docs/sdk/outcomes.md#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`.

```java theme={"theme":"github-light-default"}
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))`:

```java theme={"theme":"github-light-default"}
import java.util.Map;

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

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. 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](https://silmaril.security/docs/sdk/outcomes.md#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. Choose an explicit client mode. Use a per-call mode only when that override is intentional:

```java theme={"theme":"github-light-default"}
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()`.

```java theme={"theme":"github-light-default"}
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](https://silmaril.security/docs/sdk/outcomes.md#outcome-taxonomy).

## Next steps

[Verify your integration](https://silmaril.security/docs/start/verify.md), then review [modes and enforcement](https://silmaril.security/docs/guides/enforcement.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.