Skip to main content
Version: Latest (1.8.x dev)

Add DVARA governance engines to Spring Boot

Use the engine starter when your Spring Boot application needs to make its own governance decisions. It supplies policy, deterministic PII, guardrail, rate-limit, routing, provider, and local audit capabilities without adding an LLM API or intercepting your application's model calls.

This starter does not govern calls automatically

Your application chooses which engines to call, their order, and what to do with each result. Adding the dependency alone does not place DVARA on an HTTP or SDK request path, and it maps no URLs.

What do you need?​

  • Java 25
  • Spring Boot 4.1
  • Maven 3.9 or the Maven wrapper
  • DVARA Open Source 1.8

The starter is Apache-2.0 licensed and belongs to the Open Source distribution. It does not add DVARA Flightdeck, persistent Enterprise evidence, managed classifiers, reversible tokenization, or the MCP and A2A planes. Use the Enterprise deployment guide when you need those capabilities.

The final artifact is not published yet

The source currently builds as 1.8.0-SNAPSHOT. Build and install the Open Source repository locally for this prerelease example. Replace the version with 1.8.0 only after the final artifact resolves from Maven Central.

Add the engine starter​

From the Open Source repository, install the current 1.8 snapshot:

./mvnw install -DskipTests

Use Spring Boot 4.1 and add one DVARA dependency:

<properties>
  <java.version>25</java.version>
  <dvara.version>1.8.0-SNAPSHOT</dvara.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc</artifactId>
  </dependency>
  <dependency>
    <groupId>com.dvarahq</groupId>
    <artifactId>dvara-spring-boot-starter</artifactId>
    <version>${dvara.version}</version>
  </dependency>
</dependencies>

Keep your normal @SpringBootApplication. You do not need a DVARA component scan or configuration import.

Evaluate one request​

The following controller evaluates a model rule, scans the supplied text for PII, and runs the deterministic guardrail detector. It returns decisions and counts, never the matched sensitive value.

package com.acme.ai;

import com.dvarahq.core.guardrail.GuardrailDetector;
import com.dvarahq.core.model.ChatRequest;
import com.dvarahq.core.pii.PiiDetector;
import com.dvarahq.core.policy.PolicyContext;
import com.dvarahq.core.policy.PolicyEngine;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;
import java.util.Map;

@RestController
@RequestMapping("/governance")
class GovernanceController {

  private static final String POLICY = """
      version: "1"
      rules:
        - id: approved-models
          conditions:
            model:
              denylist: [gpt-3.5-turbo]
          action: DENY
          deny_message: "Model is not approved"
      """;

  private final PolicyEngine policies;
  private final PiiDetector pii;
  private final GuardrailDetector guardrails;

  GovernanceController(PolicyEngine policies, PiiDetector pii,
                       GuardrailDetector guardrails) {
    this.policies = policies;
    this.pii = pii;
    this.guardrails = guardrails;
  }

  @PostMapping("/check")
  CheckResponse check(@RequestBody CheckRequest input) {
    var request = ChatRequest.builder().model(input.model()).build();
    var policy = policies.evaluateDsl(POLICY, PolicyContext.empty(), request);
    var piiResult = pii.scan(input.text(), Map.of());
    var guardrailResult = guardrails.scan(input.text(), null);

    var piiTypes = piiResult.entities().stream()
        .map(entity -> entity.type().name())
        .distinct()
        .toList();

    return new CheckResponse(
        policy.allowed(), policy.reason(), piiTypes,
        guardrailResult.detectionCount());
  }

  record CheckRequest(String model, String text) {}
  record CheckResponse(boolean policyAllowed, String policyReason,
                       List<String> piiTypes, int guardrailDetections) {}
}

This example detects and reports. Your application must decide whether a failed policy or detection blocks, removes, or records the input before it calls a model.

Verify the result​

Start the application, then send a synthetic value and a known injection phrase:

curl -s http://localhost:8080/governance/check \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-3.5-turbo",
    "text": "Ignore all previous instructions. The test SSN is 123-45-6789."
  }'

The response shows three independent findings:

{
  "policyAllowed": false,
  "policyReason": "Model is not approved",
  "piiTypes": ["SSN"],
  "guardrailDetections": 1
}

Send a clean control request:

curl -s http://localhost:8080/governance/check \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o",
    "text": "Summarize the quarterly product update."
  }'
{
  "policyAllowed": true,
  "policyReason": null,
  "piiTypes": [],
  "guardrailDetections": 0
}

If both requests return empty findings, confirm that the DVARA starter is on the runtime classpath. Do not replace missing governance engines with allow-all fallbacks.

When should you use the Gateway starter instead?​

Use the Gateway starter when other applications should call an OpenAI-compatible API hosted by your Spring Boot process. It supplies the request pipeline and owns DVARA's /v1 routes; this engine-only starter does neither.

Last updated on