Skip to content

LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows

UN-3493 [FEAT] Add AWS Bedrock Guardrails support to Bedrock LLM adapter (#1996)

Chandrasekharan M280dbb4698e1
diff --git a/unstract/sdk1/src/unstract/sdk1/adapters/base1.py b/unstract/sdk1/src/unstract/sdk1/adapters/base1.py
index 467b1ff25..da154f36a 100644
--- a/unstract/sdk1/src/unstract/sdk1/adapters/base1.py
+++ b/unstract/sdk1/src/unstract/sdk1/adapters/base1.py
@@ -852,6 +852,35 @@ def _resolve_bedrock_aws_credentials(
return validated
+def _pack_bedrock_guardrail_config(metadata: dict[str, "Any"]) -> None:
+ """Translate snake_case guardrail_* fields into LiteLLM's guardrailConfig."""
+ identifier = _clean_str(metadata.get("guardrail_identifier"))
+ if not identifier:
+ return
+ version = _clean_str(metadata.get("guardrail_version"))
+ # Fail fast — Bedrock rejects identifier without version with an opaque error.
+ if not version:
+ raise ValueError(
+ "guardrail_version is required when guardrail_identifier is set."
+ )
+ cfg: dict[str, str] = {
+ "guardrailIdentifier": identifier,
+ "guardrailVersion": version,
+ }
+ trace = _clean_str(metadata.get("guardrail_trace"))
+ if trace:
+ cfg["trace"] = trace
+ metadata["guardrailConfig"] = cfg
+
+
+def _clean_str(value: str | None) -> str | None:
+ """Strip surrounding whitespace; return None if the result is empty."""
+ if value is None:
+ return None
+ stripped = value.strip()
+ return stripped or None
+
+
class AWSBedrockLLMParameters(BaseChatCompletionParameters):
"""See https://docs.litellm.ai/docs/providers/bedrock."""
@@ -866,6 +895,9 @@ class AWSBedrockLLMParameters(BaseChatCompletionParameters):
aws_profile_name: str | None = None # For AWS SSO authentication
model_id: str | None = None # For Application Inference Profile (cost tracking)
max_retries: int | None = None
+ # Declared so it survives Pydantic re-validation of kwargs.
+ # Matches LiteLLM's Bedrock kwarg name, hence the mixed case.
+ guardrailConfig: dict | None = None # noqa: N815
@staticmethod
def validate(adapter_metadata: dict[str, "Any"]) -> dict[str, "Any"]:
@@ -908,16 +940,31 @@ class AWSBedrockLLMParameters(BaseChatCompletionParameters):
result_metadata["thinking"] = thinking_config
result_metadata["temperature"] = 1
+ _pack_bedrock_guardrail_config(result_metadata)
+
# Create validation metadata excluding control fields. `auth_type` is
# a UI-only selector that drives form rendering; LiteLLM never sees it.
validation_metadata = {
k: v
for k, v in result_metadata.items()
- if k not in ("enable_thinking", "budget_tokens", "thinking", "auth_type")
+ if k
+ not in (
+ "enable_thinking",
+ "budget_tokens",
+ "thinking",
+ "auth_type",
+ "guardrail_identifier",
+ "guardrail_version",
+ "guardrail_trace",
+ )
}
validated = AWSBedrockLLMParameters(**validation_metadata).model_dump()
+ # Drop unset value so it isn't forwarded as `None`.
+ if not validated.get("guardrailConfig"):
+ validated.pop("guardrailConfig", None)
+
# Add thinking config to final result if enabled
if enable_thinking and "thinking" in result_metadata:
validated["thinking"] = result_metadata["thinking"]
diff --git a/unstract/sdk1/src/unstract/sdk1/adapters/llm1/static/bedrock.json b/unstract/sdk1/src/unstract/sdk1/adapters/llm1/static/bedrock.json
index fcad4991e..f092bef86 100644
--- a/unstract/sdk1/src/unstract/sdk1/adapters/llm1/static/bedrock.json
+++ b/unstract/sdk1/src/unstract/sdk1/adapters/llm1/static/bedrock.json
@@ -19,20 +19,62 @@
"default": "amazon.titan-text-express-v1",
"description": "Model name. Refer to [Bedrock's documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) for the list of available models."
},
- "region_name": {
+ "model_id": {
"type": "string",
- "title": "AWS Region Name",
- "description": "Provide the AWS Region name where the service is running. Eg. us-east-1"
+ "title": "Application Inference Profile ARN",
+ "description": "Optional ARN for Application Inference Profile for cost tracking. Example: arn:aws:bedrock:us-east-1:000000000000:application-inference-profile/xxxx"
+ },
+ "auth_type": {
+ "type": "string",
+ "title": "Authentication Type",
+ "enum": [
+ "access_keys",
+ "iam_role",
+ "bearer_token"
+ ],
+ "enumNames": [
+ "Access Keys",
+ "IAM Role / Instance Profile (on-prem AWS only)",
+ "Bedrock API Key (Bearer Token)"
+ ],
+ "default": "access_keys",
+ "description": "Choose **Access Keys** for any deployment (provide your AWS Access Key ID and Secret). Choose **IAM Role / Instance Profile** only when Unstract is hosted on AWS infrastructure that already has ambient credentials — for example EKS pods with IRSA, ECS tasks with a task role, or EC2 instances with an instance profile. Choose **Bedrock API Key (Bearer Token)** to authenticate with an AWS Bedrock API key (`AWS_BEARER_TOKEN_BEDROCK`). The token is region-scoped — ensure the AWS Region below matches the key's region."
},
"aws_profile_name": {
"type": "string",
"title": "AWS Profile Name",
"description": "AWS SSO profile name for authentication. Use this instead of access keys when using AWS SSO. Example: dev-profile"
},
- "model_id": {
+ "region_name": {
"type": "string",
- "title": "Application Inference Profile ARN",
- "description": "Optional ARN for Application Inference Profile for cost tracking. Example: arn:aws:bedrock:us-east-1:000000000000:application-inference-profile/xxxx"
+ "title": "AWS Region Name",
+ "description": "Provide the AWS Region name where the service is running. Eg. us-east-1"
+ },
+ "enable_thinking": {
+ "type": "boolean",
+ "title": "Enable Extended Thinking",
+ "default": false,
+ "description": "Enhance reasoning for complex tasks with step-by-step transparency. Available only for Claude 3.7 Sonnet."
+ },
+ "guardrail_identifier": {
+ "type": "string",
+ "title": "Bedrock Guardrail Identifier",
+ "description": "Optional. Apply an [AWS Bedrock Guardrail](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) to moderate prompts and completions. Provide the guardrail ID (e.g. `ff6ujrregl1q`). Leave blank to disable."
+ },
+ "guardrail_version": {
+ "type": "string",
+ "title": "Bedrock Guardrail Version",
+ "description": "Version of the guardrail to apply. Use `DRAFT` for the working draft or a numeric version like `1`. Required when `Bedrock Guardrail Identifier` is set."
+ },
+ "guardrail_trace": {
+ "type": "string",
+ "title": "Bedrock Guardrail Trace",
+ "enum": [
+ "enabled",
+ "disabled"
+ ],
+ "default": "disabled",
+ "description": "Enable to include guardrail trace info in the response (useful for debugging which rule was triggered)."
},
"max_tokens": {
"type": "number",
@@ -57,28 +99,6 @@
"title": "Timeout",
"default": 900,
"description": "Timeout in seconds"
- },
- "enable_thinking": {
- "type": "boolean",
- "title": "Enable Extended Thinking",
- "default": false,
- "description": "Enhance reasoning for complex tasks with step-by-step transparency. Available only for Claude 3.7 Sonnet."
- },
- "auth_type": {
- "type": "string",
- "title": "Authentication Type",
- "enum": [
- "access_keys",
- "iam_role",
- "bearer_token"
- ],
- "enumNames": [
- "Access Keys",
- "IAM Role / Instance Profile (on-prem AWS only)",
- "Bedrock API Key (Bearer Token)"
- ],
- "default": "access_keys",
- "description": "Choose **Access Keys** for any deployment (provide your AWS Access Key ID and Secret). Choose **IAM Role / Instance Profile** only when Unstract is hosted on AWS infrastructure that already has ambient credentials — for example EKS pods with IRSA, ECS tasks with a task role, or EC2 instances with an instance profile. Choose **Bedrock API Key (Bearer Token)** to authenticate with an AWS Bedrock API key (`AWS_BEARER_TOKEN_BEDROCK`). The token is region-scoped — ensure the AWS Region below matches the key's region."
}
},
"dependencies": {
@@ -175,6 +195,24 @@
"then": {
"properties": {}
}
+ },
+ {
+ "if": {
+ "properties": {
+ "guardrail_identifier": {
+ "type": "string",
+ "minLength": 1
+ }
+ },
+ "required": [
+ "guardrail_identifier"
+ ]
+ },
+ "then": {
+ "required": [
+ "guardrail_version"
+ ]
+ }
}
]
}
diff --git a/unstract/sdk1/tests/test_bedrock_adapter.py b/unstract/sdk1/tests/test_bedrock_adapter.py
index 531922970..21d6634fb 100644
--- a/unstract/sdk1/tests/test_bedrock_adapter.py
+++ b/unstract/sdk1/tests/test_bedrock_adapter.py
@@ -322,6 +322,86 @@ def test_llm_legacy_drops_stray_bearer_token() -> None:
assert "api_key" not in out
+# ── LLM: Bedrock Guardrails ──────────────────────────────────────────────────
+
+
+def _llm_base() -> dict:
+ return {
+ "auth_type": "access_keys",
+ "model": "anthropic.claude-3-haiku-20240307-v1:0",
+ "region_name": "us-east-1",
+ "aws_access_key_id": "AKIAFAKE",
+ "aws_secret_access_key": "secret",
+ }
+
+
+def test_llm_guardrail_packs_into_litellm_kwarg() -> None:
+ out = AWSBedrockLLMParameters.validate(
+ {
+ **_llm_base(),
+ "guardrail_identifier": "ff6ujrregl1q",
+ "guardrail_version": "DRAFT",
+ "guardrail_trace": "enabled",
+ }
+ )
+ assert out["guardrailConfig"] == {
+ "guardrailIdentifier": "ff6ujrregl1q",
+ "guardrailVersion": "DRAFT",
+ "trace": "enabled",
+ }
+ assert "guardrail_identifier" not in out
+
+
+def test_llm_guardrail_omitted_drops_key() -> None:
+ out = AWSBedrockLLMParameters.validate(_llm_base())
+ assert "guardrailConfig" not in out
+
+
+def test_llm_guardrail_identifier_without_version_raises() -> None:
+ """Bedrock rejects identifier without version with an opaque error — fail fast."""
+ with pytest.raises(ValueError, match="guardrail_version is required"):
+ AWSBedrockLLMParameters.validate(
+ {**_llm_base(), "guardrail_identifier": "ff6ujrregl1q"}
+ )
+
+
+def test_llm_guardrail_whitespace_identifier_treated_as_absent() -> None:
+ out = AWSBedrockLLMParameters.validate({**_llm_base(), "guardrail_identifier": " "})
+ assert "guardrailConfig" not in out
+
+
+def test_llm_guardrail_whitespace_version_raises() -> None:
+ with pytest.raises(ValueError, match="guardrail_version is required"):
+ AWSBedrockLLMParameters.validate(
+ {
+ **_llm_base(),
+ "guardrail_identifier": "ff6ujrregl1q",
+ "guardrail_version": " ",
+ }
+ )
+
+
+def test_llm_guardrail_strips_surrounding_whitespace() -> None:
+ out = AWSBedrockLLMParameters.validate(
+ {
+ **_llm_base(),
+ "guardrail_identifier": " ff6ujrregl1q ",
+ "guardrail_version": " DRAFT ",
+ }
+ )
+ assert out["guardrailConfig"]["guardrailIdentifier"] == "ff6ujrregl1q"
+ assert out["guardrailConfig"]["guardrailVersion"] == "DRAFT"
+
+
+def test_llm_guardrail_survives_revalidation() -> None:
+ """`LLM.complete()` re-validates self.kwargs — guardrailConfig must round-trip."""
+ first = AWSBedrockLLMParameters.validate(
+ {**_llm_base(), "guardrail_identifier": "g", "guardrail_version": "1"}
+ )
+ second = AWSBedrockLLMParameters.validate(dict(first))
+ assert second["guardrailConfig"] == first["guardrailConfig"]
+
+
# ── Embedding: same auth_type matrix ─────────────────────────────────────────