LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
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.pyindex 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 authenticationmodel_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@staticmethoddef validate(adapter_metadata: dict[str, "Any"]) -> dict[str, "Any"]:@@ -908,16 +940,31 @@ class AWSBedrockLLMParameters(BaseChatCompletionParameters):result_metadata["thinking"] = thinking_configresult_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: vfor 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 enabledif 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.jsonindex 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.pyindex 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 ─────────────────────────────────────────