@wmaurer/effect-ai-amazon-bedrock 0.3.0 → 0.4.1

package/src/AmazonBedrockSchema.ts

@@ -377,6 +377,79 @@ export class CitationsContentBlock extends Schema.Class<CitationsContentBlock>(
   citations: Schema.optional(Schema.Array(Citation))
 }) {}
 
+/**
+ * The role a guarded text block plays in a contextual grounding check.
+ *
+ * **Details**
+ *
+ * `grounding_source` marks the documents an answer must be grounded in,
+ * `query` marks the question, and `guard_content` marks text the guardrail
+ * evaluates without a grounding role.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.4.0
+ */
+export const GuardrailConverseContentQualifier = Schema.Literals(["grounding_source", "query", "guard_content"])
+
+/**
+ * Text that the guardrail evaluates.
+ *
+ * **Details**
+ *
+ * `qualifiers` uses `optionalKey` for the same reason as
+ * `CachePointBlock.ttl`: the block is built from `Prompt` provider options,
+ * whose values must satisfy `Schema.Json`.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.4.0
+ */
+export class GuardrailConverseTextBlock extends Schema.Class<GuardrailConverseTextBlock>(
+  makeIdentifier("GuardrailConverseTextBlock")
+)({
+  text: Schema.String,
+  qualifiers: Schema.optionalKey(Schema.Array(GuardrailConverseContentQualifier))
+}) {}
+
+/**
+ * An image that the guardrail evaluates.
+ *
+ * **Details**
+ *
+ * The Smithy model allows only png and jpeg, and only `bytes` as the source.
+ * `bytes` is a Smithy blob, which the JSON protocol carries as a base64
+ * string.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.4.0
+ */
+export class GuardrailConverseImageBlock extends Schema.Class<GuardrailConverseImageBlock>(
+  makeIdentifier("GuardrailConverseImageBlock")
+)({
+  format: Schema.Literals(["png", "jpeg"]),
+  source: Schema.Struct({ bytes: Schema.String })
+}) {}
+
+/**
+ * Content that the guardrail evaluates, in a message or in the system prompt.
+ *
+ * **Details**
+ *
+ * AWS models `GuardrailConverseContentBlock` as a UNION, so both members are
+ * optional here. Once a request holds one `guardContent` block, the guardrail
+ * evaluates only the guarded blocks. The model still reads every block.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.4.0
+ */
+export const GuardrailConverseContentBlock = Schema.Struct({
+  text: Schema.optional(GuardrailConverseTextBlock),
+  image: Schema.optional(GuardrailConverseImageBlock)
+})
+
 /**
  * A text content block within a Converse message.
  *
@@ -401,7 +474,8 @@ export const ContentBlock = Schema.Struct({
   image: Schema.optional(ImageBlock),
   document: Schema.optional(DocumentBlock),
   cachePoint: Schema.optional(CachePointBlock),
-  citationsContent: Schema.optional(CitationsContentBlock)
+  citationsContent: Schema.optional(CitationsContentBlock),
+  guardContent: Schema.optional(GuardrailConverseContentBlock)
 })
 
 /**
@@ -421,8 +495,9 @@ export class Message extends Schema.Class<Message>(makeIdentifier("Message"))({
  *
  * **Details**
  *
- * AWS models `SystemContentBlock` as a UNION, so both members are optional; a
- * block carries either the system text or a cache point.
+ * AWS models `SystemContentBlock` as a UNION, so every member is optional; a
+ * block carries the system text, guarded system text, or a cache point. The
+ * guardrail evaluates the system prompt only where it is guarded.
  *
  * @stability unstable
  * @category schemas
@@ -430,7 +505,8 @@ export class Message extends Schema.Class<Message>(makeIdentifier("Message"))({
  */
 export const SystemContentBlock = Schema.Struct({
   text: Schema.optional(Schema.String),
-  cachePoint: Schema.optional(CachePointBlock)
+  cachePoint: Schema.optional(CachePointBlock),
+  guardContent: Schema.optional(GuardrailConverseContentBlock)
 })
 
 /**
@@ -578,7 +654,80 @@ export const OutputConfig = Schema.Struct({
 })
 
 /**
- * The request payload for the Converse and ConverseStream operations.
+ * Whether Bedrock returns the guardrail trace.
+ *
+ * **Details**
+ *
+ * Bedrock's default is `disabled`. The trace holds the text that a policy
+ * matched, unmasked. `enabled_full` is in the Smithy model, and AWS does not
+ * document it.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.4.0
+ */
+export const GuardrailTrace = Schema.Literals(["enabled", "disabled", "enabled_full"])
+
+/**
+ * How ConverseStream applies a guardrail to the streamed output.
+ *
+ * **Details**
+ *
+ * `sync`, Bedrock's default, holds back each chunk until the guardrail has
+ * evaluated it. `async` sends chunks at once, so text that the guardrail
+ * later blocks can reach the caller, and masking does not apply.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.4.0
+ */
+export const GuardrailStreamProcessingMode = Schema.Literals(["sync", "async"])
+
+// Smithy gives the identifier and the version `default: ""`, and Bedrock cannot
+// apply a guardrail without them, so both are required here.
+const guardrailFields = {
+  guardrailIdentifier: Schema.String,
+  guardrailVersion: Schema.String,
+  trace: Schema.optionalKey(GuardrailTrace)
+}
+
+/**
+ * The guardrail of a Converse request.
+ *
+ * **Details**
+ *
+ * `guardrailIdentifier` is the guardrail's ID or ARN, and `guardrailVersion`
+ * is a version number or `DRAFT`. Converse has no `streamProcessingMode`, so
+ * the member is typed `never`: a ConverseStream request does not fit Converse
+ * until the mode is removed.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.4.0
+ */
+export class GuardrailConfiguration extends Schema.Class<GuardrailConfiguration>(
+  makeIdentifier("GuardrailConfiguration")
+)({
+  ...guardrailFields,
+  streamProcessingMode: Schema.optionalKey(Schema.Never)
+}) {}
+
+/**
+ * The guardrail of a ConverseStream request.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.4.0
+ */
+export class GuardrailStreamConfiguration extends Schema.Class<GuardrailStreamConfiguration>(
+  makeIdentifier("GuardrailStreamConfiguration")
+)({
+  ...guardrailFields,
+  streamProcessingMode: Schema.optionalKey(GuardrailStreamProcessingMode)
+}) {}
+
+/**
+ * The request payload for the Converse operation.
  *
  * **Details**
  *
@@ -602,9 +751,30 @@ export class ConverseRequest extends Schema.Class<ConverseRequest>(makeIdentifie
   toolConfig: Schema.optionalKey(ToolConfiguration),
   inferenceConfig: Schema.optional(InferenceConfiguration),
   outputConfig: Schema.optionalKey(OutputConfig),
-  additionalModelRequestFields: Schema.optional(Schema.Record(Schema.String, Schema.Unknown))
+  additionalModelRequestFields: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  guardrailConfig: Schema.optional(GuardrailConfiguration)
 }) {}
 
+/**
+ * The request payload for the ConverseStream operation.
+ *
+ * **Details**
+ *
+ * The members of `ConverseRequest`, with the guardrail of a stream, which
+ * adds `streamProcessingMode`. That member is the only difference between the
+ * two operations.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.4.0
+ */
+export class ConverseStreamRequest
+  extends Schema.Class<ConverseStreamRequest>(makeIdentifier("ConverseStreamRequest"))({
+    ...ConverseRequest.fields,
+    guardrailConfig: Schema.optional(GuardrailStreamConfiguration)
+  })
+{}
+
 // =============================================================================
 // Response
 // =============================================================================
@@ -634,6 +804,12 @@ export class ConverseMetrics extends Schema.Class<ConverseMetrics>(makeIdentifie
 /**
  * The response from a successful Converse call.
  *
+ * **Details**
+ *
+ * `trace` is kept as the JSON Bedrock sent. Its Smithy tree has about 90
+ * shapes that AWS still extends, and a struct would drop every member added
+ * later.
+ *
  * @stability unstable
  * @category schemas
  * @since 0.1.0
@@ -642,7 +818,8 @@ export class ConverseResponse extends Schema.Class<ConverseResponse>(makeIdentif
   output: ConverseOutput,
   usage: TokenUsage,
   stopReason: StopReason,
-  metrics: Schema.optional(ConverseMetrics)
+  metrics: Schema.optional(ConverseMetrics),
+  trace: Schema.optional(Schema.MutableJson)
 }) {}
 
 // =============================================================================
@@ -823,7 +1000,13 @@ export class MessageStopEvent extends Schema.Class<MessageStopEvent>(
 }) {}
 
 /**
- * The trailing metadata event for a Converse stream, carrying usage and metrics.
+ * The trailing metadata event for a Converse stream, carrying usage, metrics,
+ * and the trace.
+ *
+ * **Details**
+ *
+ * This is the only stream event that carries the trace. It is kept as JSON,
+ * as in `ConverseResponse`.
  *
  * @stability unstable
  * @category schemas
@@ -833,7 +1016,8 @@ export class ConverseStreamMetadataEvent extends Schema.Class<ConverseStreamMeta
   makeIdentifier("ConverseStreamMetadataEvent")
 )({
   usage: TokenUsage,
-  metrics: Schema.optional(ConverseMetrics)
+  metrics: Schema.optional(ConverseMetrics),
+  trace: Schema.optional(Schema.MutableJson)
 }) {}
 
 const ExceptionBody = Schema.Struct({

package/src/internal/errors.ts

@@ -114,10 +114,10 @@ export const mapCredentialProviderError =
 // with the exception type carried in the `x-amzn-errortype` header — NOT
 // Anthropic's nested `{ error: { type, message } }`. Schema-guarded so a
 // non-conforming body safely yields `undefined`.
-const BedrockErrorBody = Schema.Struct({
+const BedrockErrorBody = Schema.fromJsonString(Schema.Struct({
   message: Schema.optional(Schema.String),
   Message: Schema.optional(Schema.String)
-})
+}))
 
 /** @internal */
 const mapStatusCodeError = Effect.fnUntraced(function*(
@@ -137,16 +137,7 @@ const mapStatusCodeError = Effect.fnUntraced(function*(
 
   // Promote the provider's error message to the structured reason (else 5xx
   // shows "Server error" and 4xx shows a bare "HTTP <status>").
-  let json: unknown = undefined
-  // @effect-diagnostics effect/tryCatchInEffectGen:off
-  if (Predicate.isNotUndefined(body)) {
-    try {
-      json = JSON.parse(body)
-    } catch {
-      json = undefined
-    }
-  }
-  const decoded = Schema.decodeUnknownOption(BedrockErrorBody)(json)
+  const decoded = Schema.decodeUnknownOption(BedrockErrorBody)(body)
   const message = Option.isSome(decoded)
     ? decoded.value.message ?? decoded.value.Message
     : undefined
@@ -220,9 +211,23 @@ const buildInvalidRequestDescription = (params: {
     parts.push(`Response: ${truncated}`)
   }
 
+  if (params.message && dataRetentionRejection.test(params.message)) {
+    parts.push(dataRetentionHint)
+  }
+
   return parts.join(" ")
 }
 
+// Converse has no request field for the data retention mode, so the AWS message
+// alone leaves the reader looking for one. Only an account-level setting in each
+// region, which the control plane sets, makes such a model callable.
+const dataRetentionRejection = /data retention mode '[^']*' is not available for this model/
+
+const dataRetentionHint = "The account's data retention mode in this region does not allow this model." +
+  " Claude Fable 5 and 5.1 need `aws_review`." +
+  " Set the mode with the Bedrock PutAccountDataRetention operation:" +
+  " https://docs.aws.amazon.com/bedrock/latest/userguide/data-retention.html"
+
 /**
  * AWS sends the exception shape as `Name:http://internal.amazon.com/coral/...`.
  * Only the part before the colon identifies it.
@@ -238,7 +243,7 @@ const extractErrorType = (header: string | undefined): string | undefined =>
  * expired `aws login` credentials are the common case. The exception shape in
  * `x-amzn-errortype` is what actually distinguishes them.
  */
-const authenticationKinds: Record<string, typeof AiError.AuthenticationError.Type["kind"]> = {
+const authenticationKinds: Record<string, AiError.AuthenticationError["kind"]> = {
   AccessDeniedException: "InsufficientPermissions",
   ExpiredTokenException: "ExpiredKey",
   IncompleteSignatureException: "InvalidKey",
@@ -254,6 +259,17 @@ export const mapStatusCodeToReason = ({ errorType, http, message, status }: {
   readonly errorType?: string | undefined
   readonly http: typeof AiError.HttpContext.Type
 }): AiError.AiErrorReason => {
+  // AWS sends this with a 400, but the request is well formed. The account has
+  // used up a quota, which a short retry delay will not restore.
+  if (errorType === "ServiceQuotaExceededException") {
+    return new AiError.QuotaExhaustedError({ http })
+  }
+
+  // The exception shape is often the only clue to the cause, as when a 400
+  // arrives with the body `{}`.
+  const describe = (text: string | undefined): string | undefined =>
+    Predicate.isUndefined(errorType) ? text : Predicate.isUndefined(text) ? errorType : `${errorType}: ${text}`
+
   const invalidRequestDescription = buildInvalidRequestDescription({
     status,
     message,
@@ -267,7 +283,7 @@ export const mapStatusCodeToReason = ({ errorType, http, message, status }: {
     case 404:
     case 422:
       return new AiError.InvalidRequestError({
-        description: invalidRequestDescription,
+        description: describe(invalidRequestDescription),
         http
       })
     case 401:
@@ -276,19 +292,19 @@ export const mapStatusCodeToReason = ({ errorType, http, message, status }: {
         kind: (Predicate.isNotUndefined(errorType) ? authenticationKinds[errorType] : undefined)
           // No header, or a shape we do not know: fall back to what the status implies.
           ?? (status === 401 ? "InvalidKey" : "InsufficientPermissions"),
-        description: message,
+        description: describe(message),
         http
       })
     case 408:
       // ModelTimeoutException: the request took too long to process.
       return new AiError.InternalProviderError({
-        description: message ?? "Model timeout",
+        description: describe(message) ?? "Model timeout",
         http
       })
     case 424:
       // ModelErrorException: the model returned an error response.
       return new AiError.InternalProviderError({
-        description: message ?? "Model error",
+        description: describe(message) ?? "Model error",
         http
       })
     case 429:
@@ -298,12 +314,12 @@ export const mapStatusCodeToReason = ({ errorType, http, message, status }: {
     default:
       if (status >= 500) {
         return new AiError.InternalProviderError({
-          description: message ?? "Server error",
+          description: describe(message) ?? "Server error",
           http
         })
       }
       return new AiError.UnknownError({
-        description: message,
+        description: describe(message),
         http
       })
   }

package/src/internal/guardrails.ts

@@ -0,0 +1,91 @@
+import type * as Schema from "effect/Schema"
+import type { FinishMetadata, GuardrailAction, GuardrailOutcome } from "../AmazonBedrockLanguageModel.ts"
+
+const strength: Record<GuardrailAction, number> = { none: 0, masked: 1, blocked: 2 }
+
+const stronger = (a: GuardrailAction, b: GuardrailAction): GuardrailAction => strength[b] > strength[a] ? b : a
+
+const isObject = (value: unknown): value is Schema.MutableJsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const actionOf = (value: string): GuardrailAction =>
+  value === "BLOCKED" ? "blocked" : value === "ANONYMIZED" ? "masked" : "none"
+
+const strongestAction = (value: Schema.MutableJson): GuardrailAction => {
+  let action: GuardrailAction = "none"
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      action = stronger(action, strongestAction(item))
+    }
+  } else if (isObject(value)) {
+    for (const [key, member] of Object.entries(value)) {
+      action = stronger(
+        action,
+        key === "action" && typeof member === "string" ? actionOf(member) : strongestAction(member)
+      )
+    }
+  }
+  return action
+}
+
+const assessSide = (assessments: ReadonlyArray<Schema.MutableJson>, policies: Array<string>): GuardrailAction => {
+  let side: GuardrailAction = "none"
+  for (const assessment of assessments) {
+    if (!isObject(assessment)) {
+      continue
+    }
+    for (const [policy, member] of Object.entries(assessment)) {
+      const action = strongestAction(member)
+      if (action !== "none" && !policies.includes(policy)) {
+        policies.push(policy)
+      }
+      side = stronger(side, action)
+    }
+  }
+  return side
+}
+
+/** @internal */
+export const guardrailOutcome = (trace: Schema.MutableJson | undefined): GuardrailOutcome | null => {
+  const guardrail = isObject(trace) ? trace.guardrail : undefined
+  if (!isObject(guardrail)) {
+    return null
+  }
+  const inputAssessment = guardrail.inputAssessment
+  const outputAssessments = guardrail.outputAssessments
+  const policies: Array<string> = []
+  const input = assessSide(isObject(inputAssessment) ? Object.values(inputAssessment) : [], policies)
+  const output = assessSide(
+    isObject(outputAssessments)
+      ? Object.values(outputAssessments).flatMap((chunks) => Array.isArray(chunks) ? chunks : [])
+      : [],
+    policies
+  )
+  return { input, output, policies }
+}
+
+/** @internal */
+export const finishMetadata = (stopReason: string | null, trace: Schema.MutableJson | undefined): FinishMetadata => ({
+  stopReason,
+  guardrail: guardrailOutcome(trace),
+  trace: trace ?? null
+})
+
+const isJson = (text: string): boolean => {
+  try {
+    JSON.parse(text)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Bedrock stops with `guardrail_intervened` both when a guardrail blocks,
+ * replacing the text with the guardrail's blocked message, and when it masks,
+ * leaving the object JSON.
+ *
+ * @internal
+ */
+export const blocksObject = (stopReason: string, text: string): boolean =>
+  stopReason === "guardrail_intervened" && !isJson(text)