Python SDK

Prerequisites

Use Python 3.10 or later. Set SILMARIL_API_KEY and SILMARIL_API_URL from your deployment access.

Install

pip install silmaril-security-sdk==0.6.1

Classify your first request

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

import logging
import os

from silmaril_security.sdk import (
    Firewall,
    FirewallBlockedException,
    HookLabel,
    SilmarilApiError,
)

logging.basicConfig(level=logging.INFO)

fw = Firewall(
    api_key=os.environ["SILMARIL_API_KEY"],
    api_url=os.environ["SILMARIL_API_URL"],
)

try:
    result = fw.classify(
        "Summarize this release note.",
        hook=HookLabel.USER_INPUT,
    )
    logging.info("prediction=%s score=%.4f", result.prediction, result.score)
except FirewallBlockedException as exc:
    logging.warning("block score=%.4f threshold=%.4f", exc.score, exc.threshold)
except SilmarilApiError as exc:
    logging.error("Silmaril API error: %s", exc)
    raise

For tool output, pass the tool name as well.

fw.classify(
    tool_output,
    hook=HookLabel.TOOL_RESPONSE,
    tool_name="read_file",
)

Expected result

A benign request logs prediction=BENIGN and its score. When the effective mode is block, a malicious request raises FirewallBlockedException. Its result 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. SilmarilApiError means the API returned a non-2xx response after retries. Network failures raise the underlying requests exception. Neither is a verdict, so decide whether that boundary fails open or closed. LangChain and LangGraph handlers for this client are documented in Framework SDKs.

Async classify

Install async support before using AsyncFirewall.

pip install "silmaril-security-sdk[async]==0.6.1"

import asyncio
import os
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from silmaril_security.sdk import AsyncFirewall, HookLabel

@asynccontextmanager
async def firewall_lifespan() -> AsyncIterator[AsyncFirewall]:
    async with AsyncFirewall(
        api_key=os.environ["SILMARIL_API_KEY"],
        api_url=os.environ["SILMARIL_API_URL"],
    ) as fw:
        yield fw  # share with request handlers until shutdown

async def handle_request(fw: AsyncFirewall, first_input: str, second_input: str):
    return await asyncio.gather(
        fw.classify(first_input, hook=HookLabel.USER_INPUT),
        fw.classify(second_input, hook=HookLabel.USER_INPUT),
    )

Share one AsyncFirewall across tasks on one event loop for the service lifetime and close it at shutdown. Cancellation stops the calling task’s request. Async calls raise the same block exceptions as the synchronous client. For a synchronous off-thread fallback, create one Firewall per worker thread.

Shadow mode

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

import logging
import os
from silmaril_security.sdk import ClassifyEvent, Firewall, HookLabel

def on_classify(event: ClassifyEvent) -> None:
    if event.blocked and event.shadow_mode:
        logging.info("would block %s score=%.4f", event.hook, event.result.score)

fw = Firewall(
    api_key=os.environ["SILMARIL_API_KEY"],
    api_url=os.environ["SILMARIL_API_URL"],
    shadow_mode=True,
    on_classify=on_classify,
)

fw.classify(text, hook=HookLabel.TOOL_RESPONSE, shadow_mode=False)

The last call passes shadow_mode=False, so that call enforces.

Errors

Direct calls raise FirewallBlockedException when a block is enforced. It carries score, threshold, and the full result.

try:
    fw.classify(user_input, hook=HookLabel.USER_INPUT)
except FirewallBlockedException as exc:
    logging.warning("blocked score=%.4f threshold=%.4f", exc.score, exc.threshold)

Read exc.result for the verdict, or use shadow mode when you need the result without a block exception. 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

Async classify

Shadow mode

Errors

​Prerequisites

​Install

​Classify your first request

​Expected result

​Async classify

​Shadow mode

​Errors

Prerequisites

Install

Classify your first request

Expected result

Async classify

Shadow mode

Errors