@strands-agents/sdk 0.0.1

package/dist/src/types/messages.d.ts

@@ -0,0 +1,438 @@
+import type { JSONValue } from './json.js';
+import type { ImageBlockData, VideoBlockData, DocumentBlockData } from './media.js';
+import { ImageBlock, VideoBlock, DocumentBlock } from './media.js';
+/**
+ * Message types and content blocks for conversational AI interactions.
+ *
+ * This module follows a pattern where <name>Data interfaces define the structure
+ * for objects, while corresponding classes extend those interfaces with additional
+ * functionality and type discrimination.
+ */
+/**
+ * Data for a message.
+ */
+export interface MessageData {
+    /**
+     * The role of the message sender.
+     */
+    role: Role;
+    /**
+     * Array of content blocks that make up this message.
+     */
+    content: ContentBlockData[];
+}
+/**
+ * A message in a conversation between user and assistant.
+ * Each message has a role (user or assistant) and an array of content blocks.
+ */
+export declare class Message {
+    /**
+     * Discriminator for message type.
+     */
+    readonly type: "message";
+    /**
+     * The role of the message sender.
+     */
+    readonly role: Role;
+    /**
+     * Array of content blocks that make up this message.
+     */
+    readonly content: ContentBlock[];
+    constructor(data: {
+        role: Role;
+        content: ContentBlock[];
+    });
+    /**
+     * Creates a Message instance from MessageData.
+     */
+    static fromMessageData(data: MessageData): Message;
+}
+/**
+ * Role of a message in a conversation.
+ * Can be either 'user' (human input) or 'assistant' (model response).
+ */
+export type Role = 'user' | 'assistant';
+/**
+ * A block of content within a message.
+ * Content blocks can contain text, tool usage requests, tool results, reasoning content, cache points, guard content, or media (image, video, document).
+ *
+ * This is a discriminated union where the object key determines the content format.
+ *
+ * @example
+ * ```typescript
+ * if ('text' in block) {
+ *   console.log(block.text.text)
+ * }
+ * ```
+ */
+export type ContentBlockData = TextBlockData | {
+    toolUse: ToolUseBlockData;
+} | {
+    toolResult: ToolResultBlockData;
+} | {
+    reasoning: ReasoningBlockData;
+} | {
+    cachePoint: CachePointBlockData;
+} | {
+    guardContent: GuardContentBlockData;
+} | {
+    image: ImageBlockData;
+} | {
+    video: VideoBlockData;
+} | {
+    document: DocumentBlockData;
+};
+export type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ReasoningBlock | CachePointBlock | GuardContentBlock | ImageBlock | VideoBlock | DocumentBlock;
+/**
+ * Data for a text block.
+ */
+export interface TextBlockData {
+    /**
+     * Plain text content.
+     */
+    text: string;
+}
+/**
+ * Text content block within a message.
+ */
+export declare class TextBlock implements TextBlockData {
+    /**
+     * Discriminator for text content.
+     */
+    readonly type: "textBlock";
+    /**
+     * Plain text content.
+     */
+    readonly text: string;
+    constructor(data: string);
+}
+/**
+ * Data for a tool use block.
+ */
+export interface ToolUseBlockData {
+    /**
+     * The name of the tool to execute.
+     */
+    name: string;
+    /**
+     * Unique identifier for this tool use instance.
+     */
+    toolUseId: string;
+    /**
+     * The input parameters for the tool.
+     * This can be any JSON-serializable value.
+     */
+    input: JSONValue;
+}
+/**
+ * Tool use content block.
+ */
+export declare class ToolUseBlock implements ToolUseBlockData {
+    /**
+     * Discriminator for tool use content.
+     */
+    readonly type: "toolUseBlock";
+    /**
+     * The name of the tool to execute.
+     */
+    readonly name: string;
+    /**
+     * Unique identifier for this tool use instance.
+     */
+    readonly toolUseId: string;
+    /**
+     * The input parameters for the tool.
+     * This can be any JSON-serializable value.
+     */
+    readonly input: JSONValue;
+    constructor(data: ToolUseBlockData);
+}
+/**
+ * Content within a tool result.
+ * Can be either text or structured JSON data.
+ *
+ * This is a discriminated union where the object key determines the content format.
+ */
+export type ToolResultContentData = TextBlockData | JsonBlockData;
+export type ToolResultContent = TextBlock | JsonBlock;
+/**
+ * Data for a tool result block.
+ */
+export interface ToolResultBlockData {
+    /**
+     * The ID of the tool use that this result corresponds to.
+     */
+    toolUseId: string;
+    /**
+     * Status of the tool execution.
+     */
+    status: 'success' | 'error';
+    /**
+     * The content returned by the tool.
+     */
+    content: ToolResultContentData[];
+    /**
+     * The original error object when status is 'error'.
+     * Available for inspection by hooks, error handlers, and event loop.
+     * Tools must wrap non-Error thrown values into Error objects.
+     */
+    error?: Error;
+}
+/**
+ * Tool result content block.
+ */
+export declare class ToolResultBlock implements ToolResultBlockData {
+    /**
+     * Discriminator for tool result content.
+     */
+    readonly type: "toolResultBlock";
+    /**
+     * The ID of the tool use that this result corresponds to.
+     */
+    readonly toolUseId: string;
+    /**
+     * Status of the tool execution.
+     */
+    readonly status: 'success' | 'error';
+    /**
+     * The content returned by the tool.
+     */
+    readonly content: ToolResultContent[];
+    /**
+     * The original error object when status is 'error'.
+     * Available for inspection by hooks, error handlers, and event loop.
+     * Tools must wrap non-Error thrown values into Error objects.
+     */
+    readonly error?: Error;
+    constructor(data: {
+        toolUseId: string;
+        status: 'success' | 'error';
+        content: ToolResultContent[];
+        error?: Error;
+    });
+}
+/**
+ * Data for a reasoning block.
+ */
+export interface ReasoningBlockData {
+    /**
+     * The text content of the reasoning process.
+     */
+    text?: string;
+    /**
+     * A cryptographic signature for verification purposes.
+     */
+    signature?: string;
+    /**
+     * The redacted content of the reasoning process.
+     */
+    redactedContent?: Uint8Array;
+}
+/**
+ * Reasoning content block within a message.
+ */
+export declare class ReasoningBlock implements ReasoningBlockData {
+    /**
+     * Discriminator for reasoning content.
+     */
+    readonly type: "reasoningBlock";
+    /**
+     * The text content of the reasoning process.
+     */
+    readonly text?: string;
+    /**
+     * A cryptographic signature for verification purposes.
+     */
+    readonly signature?: string;
+    /**
+     * The redacted content of the reasoning process.
+     */
+    readonly redactedContent?: Uint8Array;
+    constructor(data: ReasoningBlockData);
+}
+/**
+ * Data for a cache point block.
+ */
+export interface CachePointBlockData {
+    /**
+     * The cache type. Currently only 'default' is supported.
+     */
+    cacheType: 'default';
+}
+/**
+ * Cache point block for prompt caching.
+ * Marks a position in a message or system prompt where caching should occur.
+ */
+export declare class CachePointBlock implements CachePointBlockData {
+    /**
+     * Discriminator for cache point.
+     */
+    readonly type: "cachePointBlock";
+    /**
+     * The cache type. Currently only 'default' is supported.
+     */
+    readonly cacheType: 'default';
+    constructor(data: CachePointBlockData);
+}
+/**
+ * Data for a JSON block.
+ */
+export interface JsonBlockData {
+    /**
+     * Structured JSON data.
+     */
+    json: JSONValue;
+}
+/**
+ * JSON content block within a message.
+ * Used for structured data returned from tools or model responses.
+ */
+export declare class JsonBlock implements JsonBlockData {
+    /**
+     * Discriminator for JSON content.
+     */
+    readonly type: "jsonBlock";
+    /**
+     * Structured JSON data.
+     */
+    readonly json: JSONValue;
+    constructor(data: JsonBlockData);
+}
+/**
+ * Reason why the model stopped generating content.
+ *
+ * - `contentFiltered` - Content was filtered by safety mechanisms
+ * - `endTurn` - Natural end of the model's turn
+ * - `guardrailIntervened` - A guardrail policy stopped generation
+ * - `maxTokens` - Maximum token limit was reached
+ * - `stopSequence` - A stop sequence was encountered
+ * - `toolUse` - Model wants to use a tool
+ */
+export type StopReason = 'contentFiltered' | 'endTurn' | 'guardrailIntervened' | 'maxTokens' | 'stopSequence' | 'toolUse' | 'modelContextWindowExceeded' | string;
+/**
+ * System prompt for guiding model behavior.
+ * Can be a simple string or an array of content blocks for advanced caching.
+ *
+ * @example
+ * ```typescript
+ * // Simple string
+ * const prompt: SystemPrompt = 'You are a helpful assistant'
+ *
+ * // Array with cache points for advanced caching
+ * const prompt: SystemPrompt = [
+ *   { textBlock: new TextBlock('You are a helpful assistant') },
+ *   { textBlock: new TextBlock(largeContextDocument) },
+ *   { cachePointBlock: new CachePointBlock({ cacheType: 'default' }) }
+ * ]
+ * ```
+ */
+export type SystemPrompt = string | SystemContentBlock[];
+/**
+ * Data representation of a system prompt.
+ * Can be a simple string or an array of system content block data for advanced caching.
+ *
+ * This is the data interface counterpart to SystemPrompt, following the <name>Data pattern.
+ */
+export type SystemPromptData = string | SystemContentBlockData[];
+/**
+ * Converts SystemPromptData to SystemPrompt by converting data blocks to class instances.
+ * If already in SystemPrompt format (class instances), returns as-is.
+ *
+ * @param data - System prompt data to convert
+ * @returns SystemPrompt with class-based content blocks
+ */
+export declare function systemPromptFromData(data: SystemPromptData | SystemPrompt): SystemPrompt;
+/**
+ * A block of content within a system prompt.
+ * Supports text content, cache points, and guard content for prompt caching and guardrail evaluation.
+ *
+ * This is a discriminated union where the object key determines the block format.
+ */
+export type SystemContentBlockData = TextBlockData | {
+    cachePoint: CachePointBlockData;
+} | {
+    guardContent: GuardContentBlockData;
+};
+export type SystemContentBlock = TextBlock | CachePointBlock | GuardContentBlock;
+/**
+ * Qualifier for guard content.
+ * Specifies how the content should be evaluated by guardrails.
+ *
+ * - `grounding_source` - Content to check for grounding/factuality
+ * - `query` - User query to evaluate
+ * - `guard_content` - General content for guardrail evaluation
+ */
+export type GuardQualifier = 'grounding_source' | 'query' | 'guard_content';
+/**
+ * Image format for guard content.
+ * Only formats supported by Bedrock guardrails.
+ */
+export type GuardImageFormat = 'png' | 'jpeg';
+/**
+ * Source for guard content image.
+ * Only supports raw bytes.
+ */
+export type GuardImageSource = {
+    bytes: Uint8Array;
+};
+/**
+ * Text content to be evaluated by guardrails.
+ */
+export interface GuardContentText {
+    /**
+     * Qualifiers that specify how this content should be evaluated.
+     */
+    qualifiers: GuardQualifier[];
+    /**
+     * The text content to be evaluated.
+     */
+    text: string;
+}
+/**
+ * Image content to be evaluated by guardrails.
+ */
+export interface GuardContentImage {
+    /**
+     * Image format.
+     */
+    format: GuardImageFormat;
+    /**
+     * Image source (bytes only).
+     */
+    source: GuardImageSource;
+}
+/**
+ * Data for a guard content block.
+ * Can contain either text or image content for guardrail evaluation.
+ */
+export interface GuardContentBlockData {
+    /**
+     * Text content with evaluation qualifiers.
+     */
+    text?: GuardContentText;
+    /**
+     * Image content with evaluation qualifiers.
+     */
+    image?: GuardContentImage;
+}
+/**
+ * Guard content block for guardrail evaluation.
+ * Marks content that should be evaluated by guardrails for safety, grounding, or other policies.
+ * Can be used in both message content and system prompts.
+ */
+export declare class GuardContentBlock implements GuardContentBlockData {
+    /**
+     * Discriminator for guard content.
+     */
+    readonly type: "guardContentBlock";
+    /**
+     * Text content with evaluation qualifiers.
+     */
+    readonly text?: GuardContentText;
+    /**
+     * Image content with evaluation qualifiers.
+     */
+    readonly image?: GuardContentImage;
+    constructor(data: GuardContentBlockData);
+}
+//# sourceMappingURL=messages.d.ts.map

package/dist/src/types/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../../src/types/messages.ts"],"names":[],"mappings":"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"}