@wmaurer/effect-ai-amazon-bedrock 0.2.0 → 0.4.0

package/src/AmazonBedrockSchema.ts

@@ -29,13 +29,13 @@ const makeIdentifier = (name: string) => `${prefix}/${name}`
 export const IntZeroOrGreater = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
 
 /**
- * The reason the model stopped generating a response.
+ * The stop reasons that the Smithy model of the Converse API names.
  *
  * @stability unstable
  * @category schemas
- * @since 0.1.0
+ * @since 0.3.0
  */
-export const StopReason = Schema.Literals([
+export const KnownStopReason = Schema.Literals([
   "end_turn",
   "tool_use",
   "max_tokens",
@@ -47,6 +47,29 @@ export const StopReason = Schema.Literals([
   "model_context_window_exceeded"
 ])
 
+/**
+ * The type of {@link KnownStopReason}.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.3.0
+ */
+export type KnownStopReason = typeof KnownStopReason.Type
+
+/**
+ * The reason the model stopped generating a response.
+ *
+ * **Details**
+ *
+ * Any string decodes, so a reason that Bedrock adds later, or that a model
+ * returns outside the Smithy model, does not fail the response.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.1.0
+ */
+export const StopReason = Schema.Union([KnownStopReason, Schema.StringForLiteralAutocomplete])
+
 /**
  * The type of {@link StopReason}.
  *
@@ -354,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.
  *
@@ -378,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)
 })
 
 /**
@@ -398,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
@@ -407,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)
 })
 
 /**
@@ -555,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**
  *
@@ -579,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
 // =============================================================================
@@ -611,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
@@ -619,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)
 }) {}
 
 // =============================================================================
@@ -800,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
@@ -810,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

@@ -220,9 +220,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.

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)

package/src/internal/utilities.ts

@@ -1,8 +1,10 @@
 import type * as Response from "effect/ai/Response"
-import * as Predicate from "effect/Predicate"
-import type { StopReason } from "../AmazonBedrockSchema.ts"
+import * as Schema from "effect/Schema"
+import { KnownStopReason, type StopReason } from "../AmazonBedrockSchema.ts"
 
-const finishReasonMap: Record<StopReason, Response.FinishReason> = {
+const isKnownStopReason = Schema.is(KnownStopReason)
+
+const finishReasonMap: Record<KnownStopReason, Response.FinishReason> = {
   content_filtered: "content-filter",
   end_turn: "stop",
   guardrail_intervened: "content-filter",
@@ -15,7 +17,5 @@ const finishReasonMap: Record<StopReason, Response.FinishReason> = {
 }
 
 /** @internal */
-export const resolveFinishReason = (stopReason: StopReason): Response.FinishReason => {
-  const reason = finishReasonMap[stopReason]
-  return Predicate.isUndefined(reason) ? "unknown" : reason
-}
+export const resolveFinishReason = (stopReason: StopReason): Response.FinishReason =>
+  isKnownStopReason(stopReason) ? finishReasonMap[stopReason] : "other"