Skip to content

feat: add ModelCallSimilarityGuard and deprecate SimilarityGuard - #1940

Merged
patriknw merged 8 commits into
feature/governancefrom
octonato/migrate-similarity-guard-sdk
Oct 6, 2026
Merged

patriknw merged 8 commits into
feature/governancefrom
octonato/migrate-similarity-guard-sdk

Conversation

@octonato

Copy link
Copy Markdown
Contributor

ModelCallSimilarityGuard binds to before-model-call by type and maps to the SPI SimilarityGuard marker.

Old SimilarityGuard on model-request logs a WARN naming the replacement.

reference.conf ships a disabled "default model-call jailbreak" entry and keeps the deprecated one.

Depends on https://github.com/lightbend/akka-runtime/pull/5737

@github-actions github-actions Bot added the documentation documentation related label Sep 24, 2026
@octonato
octonato force-pushed the octonato/migrate-similarity-guard-sdk branch from f9da1d0 to 514aef9 Compare October 5, 2026 19:54
@octonato
octonato changed the base branch from feature/governance to octonato/new-guardrail-spi-sdk October 5, 2026 19:54
@octonato
octonato added this pull request to stack #1983 October 5, 2026 19:55
Base automatically changed from octonato/new-guardrail-spi-sdk to feature/governance October 6, 2026 05:40
@patriknw
patriknw force-pushed the octonato/migrate-similarity-guard-sdk branch from 514aef9 to 165e615 Compare October 6, 2026 05:40
@patriknw
patriknw marked this pull request as ready for review October 6, 2026 07:18
@octonato
octonato force-pushed the octonato/migrate-similarity-guard-sdk branch 2 times, most recently from 855afcb to d2bc462 Compare October 6, 2026 08:11
"default model-call jailbreak" {
agents = ["planner-agent", "weather-agent"]
}
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

isn't this the same kind of configuration as a few lines up, but without the defaults? Do we need both?

Perhaps the "default model-call jailbreak" in reference.conf is not worth including, and we only document the full "jailbreak guard" config?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What you mean by full 'jailbreak guard'?

Anyway, this extra piece is not needed. I will merge with the above, but let me know if you see it differently.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The upper sample config is named "jailbreak guard".
I said full because it doesn't inherit any defaults from reference.conf

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I simplified the codes now. No mention on the previous or built-in.
Also no mention to the MCP limitation, because we are about to fix it as well.

There was a whole NOTE section that was not helping at all.

If someone have the old guadrails configured, they will get warnings in the logs. That should be enough to make them (or their agents) to check the docs and adapted accordingly.

@patriknw

patriknw commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

🤖 review

Findings

  1. [should-fix] akka-javasdk/src/main/scala/akka/javasdk/impl/agent/GuardrailProvider.scala:378-388: following the model-request warning as written drops checks.

    • The warning also fires for use-for = ["*"] and for model-request combined with other uses. It always says with use-for [model-request] and "Use ... ModelCallSimilarityGuard without use-for instead".
    • A user who does exactly that loses the model-response, mcp-tool-request and mcp-tool-response checks of that entry. Nothing tells them to keep those uses on a SimilarityGuard entry.
    • Verified: use-for = ["*"] logs only this text, and no model-response warning.
    • The "both guards" warning (:481-486, "Keep only one") has the same effect for a * entry.
    • GuardrailProviderSpec.scala:1306 asserts the current text.
    • Fix: name the declared uses, and tell the user to move only model-request to a ModelCallSimilarityGuard entry and keep the other uses on the old entry.
  2. [should-fix] GuardrailProvider.scala:379-383, docs/.../guardrails.adoc:251: the advice for "default jailbreak" drops the user's overrides.

    • The advice is "Enable "default model-call jailbreak" and remove "default jailbreak" from your agents". It ignores every override on the old entry.
    • Verified with report-only = true, threshold = 0.9, category = PROMPT_INJECTION, bad-examples-resource-dir = "my/own": the warning is unchanged.
    • Followed as written, the service gets the shipped dataset, threshold 0.75, JAILBREAK and report-only = false. A report-only service starts to block, and the custom dataset is no longer searched.
    • Fix: tell the user to carry the overrides over to the new entry (and to keep non-model-request uses, see 1).
  3. [should-fix] SimilarityGuard.java:11-13, guardrails.adoc:245-252, GuardrailProvider.scala:390-391: the forms disagree for model-response.

    • The javadoc and the docs cover only model-request and the MCP uses.
    • The log tells a SimilarityGuard user with model-response to "Implement ModelCallGuardrail (for model-request) or AgentResponseGuardrail (for model-response)".
    • A user of a class that ships with the SDK cannot rebuild the similarity search with the public API. The text also names model-request, which the other warning already handles. Runtime 1.7.0 has no built-in similarity guard for the agent response.
    • Fix: state the same thing in all three forms for model-response (no built-in replacement), as is done for MCP (requirement 6).
  4. [should-fix] guardrails.adoc:209-252: the docs do not say what differs after the move (requirement 3). Behaviour from the comparison below, checked in a running service:

    • The GuardrailException message gains a source suffix: ... exceeds threshold [0.75] in user message.
    • The user message is checked after the model-call sanitizers, not before.
    • The guard checks the messages after the last model answer on every model call. This includes the control-tool results that start an autonomous iteration.
    • The runtime records a guardrail decision on every model call, also on allow. A ledger write failure fails an enforcing call.
    • Startup fails on a missing dataset or a threshold outside (0, 1], which the old guard accepted.
  5. [nit] GuardrailProvider.scala:306-319: each deprecation warning repeats once per agent id and once per role of the entry. Verified: 3 copies for agents = [a, b], agent-roles = [r]. This is the pattern on the base for the generic warning, and the new warnings inherit it. Log once per entry.

  6. [nit] GuardrailProvider.scala:413-418: the error for the move the docs warn against is misleading.

    • Setting class = ModelCallSimilarityGuard on "default jailbreak" fails startup with "Guardrail [default jailbreak] must not define use-for ...". The user never set use-for; it comes from reference.conf.
    • The error does not say that, and does not name "default model-call jailbreak". use-for = null works (verified).
  7. [nit] ModelCallSimilarityGuard.java:27: the startup check accepts a regular file and an empty directory.

    • The runtime lists the directory (adding a trailing slash) with its own class loader, and reads the files with the thread context class loader.
    • A file then fails before every model call. Enforcing: every call fails. Report-only: a warning and a published error on each call, and nothing is checked. The runtime also tries to build the guard again on each call.
    • An empty directory loads no examples, so every text passes silently (the same as the old guard).
    • Directory on disk, trailing slash, and jar with directory entries: both sides accept. Jar without directory entries: both reject.
    • In the packaged image, a Maven local run and the test kit, SDK and runtime share one class loader. No case was found where the runtime loads and the check rejects.
    • The range (0, 1] fits the scores the search produces (0 to 1, compared "at or above"). The docs do not mention the check.
  8. [nit] ModelCallSimilarityGuard.java:44-58: the public surface is larger than users need.

    • threshold() and badExamplesResourceDir() serve only GuardrailProvider, which could read the entry config. Released, they are API. If you keep them, mark them as INTERNAL API + @hidden + @InternalApi, as Agent._internalSetContext does.
    • The decide javadoc says "Always throws" but does not name IllegalStateException, and does not say that decideAsync throws too.
  9. [nit] Test evidence against the running runtime is limited.

    • CI covers only the request-based agent: a block on the user message and a pass (AgentIntegrationTest.java:871, 890).
    • Not covered: a block on a tool result, report-only, a streamed reply, an autonomous agent, and the shipped "default model-call jailbreak" entry. For that entry, only the unit test at GuardrailProviderSpec.scala:1447 checks the hand-over.
    • All of these pass in a scratch run (see Verification). Add at least the tool-result and report-only cases, and use the shipped default entry in place of the "test model-call jailbreak" copy.
  10. [nit] GuardrailProvider.scala:376, 474: the two FIXME notes link no issue. Link the runtime MCP-guardrail issue that the FIXME at AgentImpl.scala:363 links. I could not check its state here (no gh).

  11. [nit] reference.conf:221: "Deprecated: use "default model-call jailbreak" instead" holds no matter which uses the entry has. For an override with MCP uses there is no replacement.

  12. [nit] GuardrailProvider.scala:372: the comment lost its reason. For *, SimilarityGuard now warns and other TextGuardrails stay silent. Say so in the comment.

  13. [nit] GuardrailSettings.scala:56-82: the UseFor restructure does not change parsing, upper-case handling, the unknown-value error, or the uses handed to the runtime at startup (still ModelRequest, *, ...).

    • Its only effect is that the warning says model-request where the base said ModelRequest. That is an improvement, and no test on the base asserted the old text.
    • UseFor now has two spellings: SDK warnings say model-request, while the runtime startup log and control record say ModelRequest.

@octonato

octonato commented Oct 6, 2026

Copy link
Copy Markdown
Contributor Author

@patriknw, applied code fixes for code review comment

@patriknw patriknw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM after moving the migration guide

You can use this for other things than jailbreak attempt detection.

[#migrating-from-similarity-guard]
=== Migrating from SimilarityGuard

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should have migration instructions in ordinary docs. We have one page for that: docs/src/modules/reference/pages/migration-guide.adoc

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good one.
Migration moved now.

@octonato
octonato force-pushed the octonato/migrate-similarity-guard-sdk branch from f574f7c to 3330435 Compare October 6, 2026 13:28
The `SimilarityGuard` deprecation warning now names the deprecated uses
the entry declares, with `*` expanded. It states that `SimilarityGuard`
will support only the MCP uses, and that the SDK has no replacement for
model-response.

- For "default jailbreak", the warning lists the settings that differ
  from "default model-call jailbreak", so the user can copy them.
- The last line tells the user to remove the agents and agent roles, or
  to keep only the MCP uses in use-for.
- The warning for an agent with both similarity guards gives the same
  advice in place of "Keep only one".
The `@deprecated` note on `SimilarityGuard` now states the same facts as
the startup warning. It covers model-response and says that
`SimilarityGuard` will support only the MCP uses. The `reference.conf`
comment on "default jailbreak" now limits the deprecation to
model-request.
The guardrails page gets a migration section. It states which
`SimilarityGuard` uses are deprecated and what replaces each one. It also
explains how to move "default jailbreak" without losing changed settings.
It lists the behaviour that differs after the move: the guard checks the
masked user message, and the service fails at startup on a missing
dataset or an out-of-range threshold.
@octonato
octonato force-pushed the octonato/migrate-similarity-guard-sdk branch from 3330435 to 62a399b Compare October 6, 2026 13:28
@patriknw

patriknw commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

CI failed with what is likely unrelated. I created issue https://github.com/lightbend/akka-runtime/issues/5861

@patriknw
patriknw merged commit 8056da9 into feature/governance Oct 6, 2026
64 of 65 checks passed
@patriknw
patriknw deleted the octonato/migrate-similarity-guard-sdk branch October 6, 2026 14:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants