Go SDK

Prerequisites

Use Go 1.22 or later. Set SILMARIL_API_KEY and SILMARIL_API_URL from your deployment access.

Install

go get github.com/Silmaril-Security/sdk-go/firewall@v0.7.1

Classify your first request

Create one client per protected system and reuse it. Label each call with the boundary it checks, and check each call’s error before making the next one.

package main

import (
	"context"
	"errors"
	"log"
	"os"

	"github.com/Silmaril-Security/sdk-go/firewall"
)

func main() {
	fw, err := firewall.New(firewall.Options{
		APIKey: os.Getenv("SILMARIL_API_KEY"),
		APIURL: os.Getenv("SILMARIL_API_URL"),
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()

	result, err := fw.Classify(ctx, "Summarize this release note.",
		firewall.WithHook(firewall.HookUserInput),
	)
	if err != nil {
		var blocked *firewall.FirewallBlockedError
		if errors.As(err, &blocked) {
			log.Printf("block score=%.4f threshold=%.4f", blocked.Score, blocked.Threshold)
			return
		}
		log.Fatalf("classify failed: %v", err)
	}

	log.Printf("prediction=%s score=%.4f", result.Prediction, result.Score)
}

In a service, pass the request context instead of context.Background(). For tool output, pass the tool name as well, and handle its error the same way.

result, err = fw.Classify(ctx, toolOutput,
	firewall.WithHook(firewall.HookToolResponse),
	firewall.WithToolName("read_file"),
)

Expected result

A benign request logs prediction=BENIGN and its score. When the effective mode is block, a malicious request returns *firewall.FirewallBlockedError. Its Result field holds the full verdict. In shadow or warn mode the call returns the result instead, so route on result.Prediction. Your deployment sets the mode unless the client or call sets Mode. Outcome meanings and recommended actions are in the outcome taxonomy. Any other error means the call did not produce a verdict. That includes *firewall.APIError for a non-2xx API response, and a network, timeout, or context error. Decide whether that boundary fails open or closed. For agent governance, WithGovernance adds typed agent and resource context to one Classify call. WithBatchGovernance supplies one optional context per ClassifyBatch item. The SDK sends these fields under metadata.silmaril.governance; the server returns an optional BlockResult.Governance decision with action, policy version, and rule ID. An explicit governance block is enforced in Block mode even with a benign prediction. Older responses can omit the decision. ClassifyBatch preserves each item’s metadata, including metadata.conversationId. The current batch classifier treats each input independently and neither reads nor updates conversation history for that batch. See Batch calls and conversation history. Go uses direct classification calls and has no Deep Agents graph adapter.

Concurrent requests

Reuse one client across goroutines for independent events or different conversations. Ordered events that share one metadata.conversationId wait for each Classify call before the next event is sent. Each Classify or ClassifyBatch call takes a context, so canceling one call also stops its retry wait. Caller-owned metadata, callbacks, and custom transports must be safe for concurrent access.

Batch calls and conversation history

ClassifyBatch preserves per-item metadata, including metadata.conversationId. The current batch classifier treats each input independently and neither reads nor updates conversation history for that batch. Giving items the same conversationId does not connect them into a sequence or attach them to previously cached history. For conversation-aware checks, send each complete event through an ordered Classify call with the same metadata.conversationId. Pass firewall.WithMetadata(firewall.ClassificationMetadata{"conversationId": conversationID}) on each Classify call. Wait for each call to finish before sending the next event for that conversation. Concurrent calls are appropriate for independent events or different conversations. 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. In Block mode, *firewall.FirewallBlockedError is the blocking error. In shadow or warn mode the call returns the verdict, which still requires that inspection. Any other error, including *firewall.APIError or a network error, means that call did not produce a verdict. Use the effective mode when routing a malicious prediction or explicit governance block: in Block mode, stop the event; in Warn mode, report the would-block finding and continue; in Shadow mode, record the would-block finding and continue. Inspecting a Warn or Shadow verdict does not mean enforcing it. See the outcome taxonomy for verdict categories.

Shadow mode

Shadow mode returns results instead of blocking errors, so you can measure would-block decisions while traffic continues. Per-call options can enforce one boundary before you change the client default.

fw, err := firewall.New(firewall.Options{
	APIKey:     os.Getenv("SILMARIL_API_KEY"),
	APIURL:     os.Getenv("SILMARIL_API_URL"),
	ShadowMode: true,
	OnClassify: func(event firewall.ClassifyEvent) {
		if event.Blocked && event.ShadowMode {
			log.Printf("would block %s score=%.4f", event.Hook, event.Result.Score)
		}
	},
})
if err != nil {
	log.Fatal(err)
}

_, err = fw.Classify(ctx, text,
	firewall.WithHook(firewall.HookToolResponse),
	firewall.WithShadowMode(false),
)

The classify call passes WithShadowMode(false), so that call enforces. OnClassify can run on overlapping calls for independent events or different conversations. Synchronize any shared state it touches. Ordered events in one conversation stay on the sequential Classify path above.

Errors

Enforced blocks return *firewall.FirewallBlockedError, which carries Score, Threshold, and Result.

var blocked *firewall.FirewallBlockedError
if errors.As(err, &blocked) {
	log.Printf("blocked score=%.4f threshold=%.4f", blocked.Score, blocked.Threshold)
	return
}

Read blocked.Result for the verdict, or use shadow mode when you need the result without a blocking error. Outcome meanings and recommended actions are in the outcome taxonomy.

Start

Concepts

SDKs

AI gateways

Integrations

Deployment

MacOS

Prerequisites

Install

Classify your first request

Expected result

Concurrent requests

Batch calls and conversation history

Shadow mode

Errors

​Prerequisites

​Install

​Classify your first request

​Expected result

​Concurrent requests

​Batch calls and conversation history

​Shadow mode

​Errors

Prerequisites

Install

Classify your first request

Expected result

Concurrent requests

Batch calls and conversation history

Shadow mode

Errors