silmaril-security-sdk 0.1.0__py3-none-any.whl

silmaril_security/sdk/__init__.py

@@ -0,0 +1,99 @@
+# Copyright (c) 2024-2026 Silmaril Security Inc. All rights reserved.
+
+"""Silmaril Firewall Python SDK."""
+
+from __future__ import annotations
+
+from silmaril_security.sdk.chunking import (
+    CHARS_PER_TOKEN,
+    CHUNK_OVERLAP,
+    CHUNK_OVERLAP_CHARS,
+    CHUNK_WINDOW,
+    CHUNK_WINDOW_CHARS,
+    MAX_INPUT_CHARS,
+    MAX_INPUT_TOKENS,
+    chunk_text,
+)
+from silmaril_security.sdk.exceptions import (
+    APIError,
+    BatchPromptBlockedException,
+    PromptBlockedException,
+    SilmarilApiError,
+)
+from silmaril_security.sdk.firewall import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_THRESHOLD,
+    DEFAULT_TIMEOUT,
+    Firewall,
+    SilmarilFirewall,
+)
+from silmaril_security.sdk.hooks import (
+    ALL_HOOKS,
+    DEFAULT_HOOK_THRESHOLDS,
+    DEFAULT_HOOKS,
+    FIREWALL_HOOK_TO_LABEL,
+    INPUT_HOOKS,
+    OUTPUT_HOOKS,
+    FirewallHook,
+    HookLabel,
+    prepend_hook,
+    prepend_tool_name,
+    resolve_hooks,
+)
+from silmaril_security.sdk.types import (
+    BlockedBatchItem,
+    BlockResult,
+    ClassifyEvent,
+    ExplainResult,
+    Prediction,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ALL_HOOKS",
+    "APIError",
+    "BlockResult",
+    "BlockedBatchItem",
+    "BatchPromptBlockedException",
+    "CHARS_PER_TOKEN",
+    "CHUNK_OVERLAP",
+    "CHUNK_OVERLAP_CHARS",
+    "CHUNK_WINDOW",
+    "CHUNK_WINDOW_CHARS",
+    "ClassifyEvent",
+    "DEFAULT_HOOKS",
+    "DEFAULT_HOOK_THRESHOLDS",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_THRESHOLD",
+    "DEFAULT_TIMEOUT",
+    "ExplainResult",
+    "FIREWALL_HOOK_TO_LABEL",
+    "Firewall",
+    "FirewallHook",
+    "HookLabel",
+    "INPUT_HOOKS",
+    "MAX_INPUT_CHARS",
+    "MAX_INPUT_TOKENS",
+    "OUTPUT_HOOKS",
+    "Prediction",
+    "PromptBlockedException",
+    "SilmarilApiError",
+    "SilmarilFirewall",
+    "chunk_text",
+    "prepend_hook",
+    "prepend_tool_name",
+    "resolve_hooks",
+]
+
+
+def __getattr__(name: str):
+    if name == "SilmarilFirewallHandler":
+        from silmaril_security.sdk.langchain import SilmarilFirewallHandler
+
+        return SilmarilFirewallHandler
+    if name == "AsyncSilmarilFirewallHandler":
+        from silmaril_security.sdk.langchain import AsyncSilmarilFirewallHandler
+
+        return AsyncSilmarilFirewallHandler
+    raise AttributeError(f"module 'silmaril_security.sdk' has no attribute {name!r}")

silmaril_security/sdk/_utils.py

@@ -0,0 +1,105 @@
+# Copyright (c) 2024-2026 Silmaril Security Inc. All rights reserved.
+
+"""Utilities for extracting text from adapter message structures."""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+_SKIP_ROLES = {"ai", "assistant"}
+_SYSTEM_ROLES = {"system"}
+_TOOL_ROLES = {"tool", "function"}
+_USER_ROLES = {"human", "user"}
+
+
+def extract_content_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+            elif isinstance(block, dict) and block.get("type") == "text":
+                parts.append(block.get("text", ""))
+        return " ".join(parts)
+    return ""
+
+
+def get_role(message: Any) -> str:
+    if isinstance(message, dict):
+        role = message.get("role", "")
+        return role.lower() if isinstance(role, str) else ""
+    role = getattr(message, "role", None)
+    if isinstance(role, str):
+        return role.lower()
+    msg_type = getattr(message, "type", "")
+    return msg_type.lower() if isinstance(msg_type, str) else ""
+
+
+def get_content(message: Any) -> Any:
+    if isinstance(message, dict):
+        return message.get("content", "")
+    return getattr(message, "content", "")
+
+
+def find_last_user_message(messages: Sequence[Any]) -> Any | None:
+    for message in reversed(messages):
+        if get_role(message) in _USER_ROLES:
+            return message
+    return None
+
+
+def extract_last_user_text(messages: Sequence[Any]) -> str:
+    last = find_last_user_message(messages)
+    if last is None:
+        return ""
+    return extract_content_text(get_content(last)).strip()
+
+
+def extract_text_from_messages(
+    messages: Sequence[Any],
+    *,
+    include_system: bool = True,
+    include_tool: bool = True,
+) -> str:
+    parts: list[str] = []
+    for message in messages:
+        role = get_role(message)
+        if role in _SKIP_ROLES:
+            continue
+        if not include_system and role in _SYSTEM_ROLES:
+            continue
+        if not include_tool and role in _TOOL_ROLES:
+            continue
+        text = extract_content_text(get_content(message)).strip()
+        if text:
+            parts.append(text)
+    return "\n".join(parts)
+
+
+def extract_text_from_prompts(prompts: Sequence[str]) -> str:
+    return "\n".join(prompt.strip() for prompt in prompts if prompt.strip())
+
+
+def extract_text_from_tool_input(input_str: str) -> str:
+    return input_str.strip()
+
+
+def extract_text_from_llm_result(response: Any) -> str:
+    parts: list[str] = []
+    for gen_list in getattr(response, "generations", []):
+        for gen in gen_list:
+            text = (getattr(gen, "text", "") or "").strip()
+            if text:
+                parts.append(text)
+    return "\n".join(parts)
+
+
+def extract_text_from_documents(documents: Sequence[Any]) -> str:
+    parts: list[str] = []
+    for doc in documents:
+        text = (getattr(doc, "page_content", "") or "").strip()
+        if text:
+            parts.append(text)
+    return "\n".join(parts)

silmaril_security/sdk/chunking.py

@@ -0,0 +1,41 @@
+# Copyright (c) 2024-2026 Silmaril Security Inc. All rights reserved.
+
+"""Client-side text chunking for long firewall inputs."""
+
+from __future__ import annotations
+
+CHARS_PER_TOKEN = 4
+
+MAX_INPUT_TOKENS = 10_240
+CHUNK_WINDOW = 400
+CHUNK_OVERLAP = 64
+
+MAX_INPUT_CHARS = MAX_INPUT_TOKENS * CHARS_PER_TOKEN
+CHUNK_WINDOW_CHARS = CHUNK_WINDOW * CHARS_PER_TOKEN
+CHUNK_OVERLAP_CHARS = CHUNK_OVERLAP * CHARS_PER_TOKEN
+CHUNK_STRIDE_CHARS = CHUNK_WINDOW_CHARS - CHUNK_OVERLAP_CHARS
+
+
+def chunk_text(text: str) -> list[str]:
+    """Split text into overlapping windows.
+
+    Short inputs are returned as a single-element list. Long inputs are split
+    into 400-token windows with a 64-token overlap, using the SDK-wide
+    4-characters-per-token approximation.
+    """
+    n = len(text)
+    if n > MAX_INPUT_CHARS:
+        raise ValueError(
+            f"firewall: input has ~{n // CHARS_PER_TOKEN} tokens ({n} chars); "
+            f"max is {MAX_INPUT_TOKENS} tokens ({MAX_INPUT_CHARS} chars)"
+        )
+    if n <= CHUNK_WINDOW_CHARS:
+        return [text]
+
+    chunks: list[str] = []
+    for start in range(0, n, CHUNK_STRIDE_CHARS):
+        end = start + CHUNK_WINDOW_CHARS
+        chunks.append(text[start:end])
+        if end >= n:
+            break
+    return chunks

silmaril_security/sdk/exceptions.py

@@ -0,0 +1,83 @@
+# Copyright (c) 2024-2026 Silmaril Security Inc. All rights reserved.
+
+"""Exceptions raised by the Silmaril Firewall SDK."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from silmaril_security.sdk.hooks import HookLabel
+from silmaril_security.sdk.types import BlockedBatchItem, BlockResult
+
+_MAX_PROMPT_DISPLAY_LEN = 100
+
+
+class SilmarilApiError(Exception):
+    """Raised when the firewall API returns a non-success HTTP status."""
+
+    def __init__(self, *, status: int, status_text: str, body: str) -> None:
+        self.status = status
+        self.status_text = status_text
+        self.body = body
+        super().__init__(f"Silmaril API error {status} {status_text}: {body}")
+
+
+APIError = SilmarilApiError
+
+
+class PromptBlockedException(Exception):
+    """Raised when a single classification meets or exceeds its threshold."""
+
+    def __init__(
+        self,
+        *,
+        score: float,
+        threshold: float,
+        prompt_text: str,
+        hook: HookLabel = HookLabel.UNKNOWN,
+        tool_name: str | None = None,
+        result: BlockResult | None = None,
+        run_id: UUID | str | None = None,
+    ) -> None:
+        self.score = score
+        self.threshold = threshold
+        self.prompt_text = prompt_text
+        self.hook = hook
+        self.tool_name = tool_name
+        self.result = result
+        self.run_id = run_id
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        truncated = self.prompt_text
+        if len(truncated) > _MAX_PROMPT_DISPLAY_LEN:
+            truncated = truncated[:_MAX_PROMPT_DISPLAY_LEN] + "..."
+        return (
+            "Prompt blocked by Silmaril Firewall "
+            f"(score={self.score:.4f}, threshold={self.threshold:.4f}): "
+            f"{truncated!r}"
+        )
+
+
+class BatchPromptBlockedException(Exception):
+    """Raised when one or more batch items meet or exceed their threshold."""
+
+    def __init__(
+        self,
+        *,
+        blocked: list[BlockedBatchItem],
+        results: list[BlockResult],
+    ) -> None:
+        self.blocked = blocked
+        self.results = results
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        if len(self.blocked) == 1:
+            item = self.blocked[0]
+            return (
+                "Batch prompt blocked by Silmaril Firewall "
+                f"at index {item.index} "
+                f"(score={item.result.score:.4f}, threshold={item.result.threshold:.4f})"
+            )
+        return f"Batch prompts blocked by Silmaril Firewall ({len(self.blocked)} items)"