Architecture¶

English | 한국어

Responsibility Boundary¶

The library provides privacy protection, tool authorization and content inspection. The following flow shows the privacy protection boundary.

Spring AI Privacy Guardrails tokenizes PII detected by analyzers before sending data to a model, replacing it with request-scoped opaque tokens. These replacement strings do not directly reveal the original values. Immediately before tool execution, it restores only the original values allowed by policy and re-protects the results afterward. When output protection is enabled, it also applies the configured policy to the final response.

flowchart TD
    A["Input · Memory · RAG"] --> B["Detect PII<br/>then tokenize it"]
    B --> C["Model"]
    C -. "Tool call" .-> D["Tool<br/>(originals only for permitted types)"]
    D -. "Tokenize PII<br/>in the result" .-> C
    C --> E["Apply final-response PII policy<br/>(when output protection is enabled)"]
    E --> F["Application"]

Detection offsets always refer to the caller-supplied input text. Analyzers return ranges, entity types, scores, and other evidence. The core module validates, canonicalizes, and resolves that evidence according to application policy. Mappings between opaque tokens and original values are managed per request through PrivacySession.

The library protects data that crosses supported model, tool, and output boundaries. The optional Spring Security integration can also authorize tool discovery and execution.

Client Composition¶

GuardrailsPolicy selects privacy protection, tool authorization and content inspection independently. GuardrailsChatClientFactory combines the selected features with shared services and returns a ChatClient.Builder. The application calls build() to create its client.

flowchart LR
    PRIVACY["Privacy<br/>PII tokenization and disclosure"] --> FACTORY["GuardrailsChatClientFactory"]
    SECURITY["Security<br/>Tool authorization"] --> FACTORY
    INSPECTION["Inspection<br/>Input and output content checks"] --> FACTORY
    FACTORY --> CLIENT["ChatClient"]

The arrows show client composition. At runtime, the selected model-request stages execute in privacy, tool authorization, then content inspection order. Output protection and output inspection are configured separately. See Configuration for setup.

Module Structure¶

The modules separate feature implementations from client assembly and Spring Boot configuration. The diagram and table omit the common spring-ai-privacy-guardrails- prefix. Solid arrows point from a module to its direct dependency. The dashed arrow shows optional integration through a configurer. Modules with the same internal dependencies are grouped in one box.

The diagram shows the main library modules. Spring Boot starters are described below.

flowchart LR
    CLIENT["chat-client"]

    subgraph PRIVACY["Privacy"]
        SAI["spring-ai"] --> CORE["core"]
        ANALYZERS["presidio<br/>opennlp"] --> CORE
    end

    subgraph SECURITY["Tool authorization"]
        SEC["spring-security"]
    end

    subgraph INSPECTION["Content inspection"]
        BACKENDS["inspection-rules<br/>inspection-onnx<br/>inspection-openai-compatible"] --> ICORE["inspection-core"]
        ISA["inspection-spring-ai"] --> ICORE
    end

    CLIENT --> ISA
    CLIENT --> SAI
    CLIENT -. "Optional integration" .-> SEC
    SAI --> BOUNDARY["spring-ai-boundary"]
    SEC --> BOUNDARY
    ISA --> BOUNDARY

chat-client integrates spring-security through a tool-authorization configurer. With Spring Boot, the configurer is supplied automatically when the Security starter and a tool-authorization policy are configured.

The client Spring Boot starter includes the privacy and inspection starters, which configure the shared services. Analyzer and inspection backend dependencies are selected separately. The Spring Security starter is optional and can also be used without the privacy starter.

core and inspection-core are independent engines for privacy protection and content inspection. Neither spring-security nor spring-ai-boundary depends on these engines.

The privacy, security and inspection integrations share spring-ai-boundary to compose the stages that run before each model call. Unconfigured stages are skipped.

The test-support module provides test-only APIs for verifying privacy behavior. Benchmarks and samples are repository-internal modules for performance measurement and runnable examples and are not published artifacts.

Library APIs and Extension Points¶

The library provides APIs used directly by applications and extension points for custom implementations. Internal implementation types are not public API and are not part of the compatibility contract.

This table shows representative APIs only. See the Javadoc for the complete public API.

Detection and Resolution¶

Each PiiAnalyzer has a unique provider ID and returns detected source ranges as PiiSpan values. The core module applies entity aliases, score thresholds, the detection allowlist, and overlap-resolution rules before deciding which ranges to protect.

Entity labels returned by analyzers are not trusted as-is. Core validates entity-label syntax and reported span ranges, then applies aliases and trusted entity types. Labels that are neither built in nor explicitly trusted are handled as the generic PII entity type.

When an application supplies PiiSpan values directly without running an analyzer, the same core rules for range validation, entity normalization, and overlap resolution still apply. Detection results retain input-text offsets and provenance rather than copying PII substrings from the input text.

The provided local rule, Presidio, and OpenNLP analyzers are implemented for safe reuse across concurrent requests. Presidio request timeouts and retries are managed through library configuration.

A custom PiiAnalyzer or PiiRule may be invoked concurrently by multiple requests and must therefore be thread-safe. If it adds blocking work such as an external service call, that work must also use an appropriate finite timeout.

Analyzer selection, failure policy, and score thresholds are configured under Detection and Resolution, which also documents overlap-resolution behavior.

Requests and Sessions¶

Mappings between opaque tokens and original values are managed per request through PrivacySession. Direct core usage and Spring AI integration use the same session model.

Each request receives a separate session, and opaque tokens created in that session are valid only within that request. The Spring AI execution context carries only a session handle. The actual mapping between opaque tokens and original values remains in library-managed internal state and is not included in model requests or tool inputs.

Within a session, PII analysis can be reused for identical input. Disclosure and authorization checks still run for each tool invocation.

A session is not bound to a specific execution thread, so tool execution can continue on another thread while using the same request session. If the session is missing or already closed, privacy processing fails instead of continuing.

With Spring AI integration, the library automatically cleans up the session mapping when a request completes, fails, or its stream is cancelled. When using the core module's PrivacyService directly, the application manages the session lifecycle explicitly.

Spring AI Execution Flow¶

The following sequence shows a privacy-enabled client. Tool authorization and content inspection run when selected. Each model call, including one after a tool returns, passes through the configured request stages.

sequenceDiagram
    participant A as Application
    participant P as Privacy Guardrails
    participant M as Model
    participant T as Tool

    A->>P: Input · Memory · RAG
    P->>P: Detect PII, then tokenize it

    P->>P: Keep only authorized tools<br/>(with tool authorization)

    P->>P: Inspect model input<br/>(with content inspection)

    P->>M: Protected model request

    opt Tool call
        M->>P: Tool call

        P->>P: Check tool execution permissions<br/>(with tool authorization)

        P->>P: Restore permitted originals
        P->>T: Execute tool
        T-->>P: Tool result
        P->>P: Tokenize PII in the tool result
        P->>P: Apply selected model-request stages again
        P-->>M: Protected tool result
    end

    M-->>P: Final response

    opt Final-response policies enabled
        P->>P: Apply selected PII protection<br/>and content inspection
    end

    P-->>A: Application output
    P->>P: Clean up session

Tool authorization uses the authentication of the user who started the request. The tool list is authorized before every model call. All requested tools are authorized before any of them execute, and each tool is checked again immediately before it runs. If execution authorization is denied for a tool, its original values are not restored and the tool is not executed. See Tool Authorization for authentication propagation and policy configuration.

PrivacyChatClientConfigurer applies the privacy configuration only to the ChatClient.Builder selected by the application and does not affect other ChatClient instances. A builder derived from an already protected client retains that privacy configuration and should not have PrivacyChatClientConfigurer applied again.

If a privacy boundary cannot resolve its required session, or if the privacy configuration is duplicated, execution fails closed rather than continuing with incomplete protection.

The privacy integration can be used with other Spring AI advisors. Changes to model input, tools, or responses made by an advisor outside the privacy boundary are outside the automatic protection scope. See advisor configuration for advisor registration.

Model and Output¶

Text in supported model-bound inputs is protected before the model provider is invoked. This includes the initial user input as well as supported message and tool-related text that is later sent to the model.

Supported Message implementations preserve the fields required by their contracts while applying privacy protection. Unsupported Message implementations fail rather than allowing unprotected data to reach the model.

When output protection is enabled, the configured policy is applied to each complete response before it is returned to the application. When a complete response must be inspected, streaming output is buffered until completion so sensitive values split across multiple stream chunks can be inspected as one response.

Apart from reasoning text explicitly supported by the library, response metadata and non-text content such as images and audio are not automatically protected.

Output policy and streaming behavior are documented under Output Policy and Streaming.

Tool Execution¶

When privacy is selected, GuardrailsChatClientFactory automatically protects registered ToolCallback and ToolCallbackProvider instances. For manual assembly, wrap them with PrivacyToolCallbackFactory. Protected tools use the current request session to restore only the permitted original values and protect their results again after execution.

Original-value disclosure to tools is default-deny. Tool registration and permission to receive original values are separate concerns: only tools configured for specific entity types receive those originals immediately before execution.

Separate execution paths that use a custom ToolCallingManager or ToolCallbackResolver are outside the automatic protection scope.

Logs written or exceptions raised inside a tool after original values have been disclosed are not re-protected and may contain those values.

Detailed disclosure rules and the returnDirect flow are documented under Per-Tool Original Disclosure.

Optional Tool Authorization Boundary¶

The Spring Security integration shows the model only tools the current user is allowed to use, then checks permission again immediately before each tool runs. Authorization checks use the user's Authentication obtained at the start of the request. Tool authorization can be used on its own or with privacy protection.

flowchart TD
    A["Request user's authentication"] --> D["Tool permission checks"]
    B["Application authorization policy"] --> D
    D --> E["Before each model call:<br/>show only authorized tools"]
    D --> F["Immediately before execution:<br/>recheck permission"]
    F --> G["Execute authorized tool"]

When tool authorization and privacy protection are used together, tool permission is checked before restoring the original PII values allowed for that tool.

The Spring Boot starter provides factories for creating clients with tool authorization. A factory applies authorization to the ChatClient it creates. The configuration of other clients, including those using the same model, is unaffected.

See Spring Security Tool Authorization for authorization policies, custom tool execution, and authentication in asynchronous calls.

Optional Content Inspection¶

Content inspection evaluates request text with rules, local ONNX text classification models or an HTTP guard model before each model call, including tool-loop continuations. When combined with privacy protection and tool authorization, it runs after privacy processing and tool-definition authorization. If the policy blocks the request, the model is not called.

Output inspection is disabled by default. When enabled, it allows or blocks model responses and returnDirect tool results before delivery to the application. If privacy output protection is also enabled, content inspection runs after it. Streaming responses, including intermediate tool-loop text, are collected before inspection. All collected frames are delivered in order only after the complete output is allowed. Content inspection does not modify text.

Input size and time limits are configured separately from privacy processing limits. See Scope and limits for the inspected fields and streaming limits, and HTTP guard models and privacy for the conditions under which text is sent to an external guard model.

Errors and Diagnostics¶

Library-owned privacy failures use PrivacyGuardrailException and PrivacyFailureCode. These failures do not include original PII or analyzer response bodies. They expose only limited diagnostic information such as the failure category and processing phase.

PiiAnalyzerFailureObserver receives the same sanitized failure information. It cannot change the analysis result, and the information can be used for operational diagnostics such as metrics, tracing, and logs.

The optional PrivacyEnforcementObserver reports PROTECTED, DISCLOSED, and BLOCKED outcomes at the model, tool-input, tool-result, and application-output boundaries. Events contain only boundary and outcome. Observer failures cannot affect privacy enforcement.

Exceptions raised by model providers, application tools, and external libraries may propagate using their original exception types. Exceptions and logs created outside the library are outside this sanitization boundary, and whether they record sensitive values depends on the logging configuration of the component that produced them.

Error codes and processing phases are documented under Privacy Error Handling.

Resource Limits and Request Cleanup¶

Privacy operations performed directly by the library, such as text transformation, structured-value traversal, analyzer-result retention, and response inspection, use processing bounds to keep memory use predictable. See Privacy Protection for the main limits and related settings.

When a Spring AI streaming request is cancelled or fails, the library cleans up the request session and the privacy mappings it manages.

Request cancellation cleans up the session but cannot forcibly stop synchronous analyzer or tool code that is already running. Such implementations need their own timeouts and cancellation handling.

These resource limits apply to privacy inspection and transformation. Execution policies such as model and tool call counts, cost, and concurrency continue to follow the application's or orchestration framework's existing settings.

Test Support¶

The spring-ai-privacy-guardrails-test module provides test utilities that can record requests sent to the model and inputs passed to tool execution. With a local ChatModel test double, they can verify without calling a remote model that PII did not reach the model, only required original values were disclosed to a tool, and the request session was cleaned up correctly.

PrivacyTestProbe is a test-only API for verifying privacy-boundary behavior. See Test Support for usage.

Analyzer Integration¶

Analyzer integration modules such as Presidio and OpenNLP translate analyzer detections into the common PiiAnalyzer contract. Regardless of which analyzer is used, downstream detection resolution and per-tool original disclosure continue to follow the shared core rules.

For a remote analyzer service such as Presidio, connection security, credentials, and deployment environment follow that service's configuration. When the application supplies a model, as with OpenNLP, the selected model can affect both detection coverage and quality.

See Privacy Protection for analyzer configuration.

Stored Data¶

ChatMemory content and RAG results are protected when supported text from them is included in model or tool input. The library does not automatically rewrite data that is already stored.

See Stored Data and Diagnostics for the detailed scope.