Crate modelrelay 

Minimal Rust SDK for the ModelRelay API.

Re-exports

pub use tools::assistant_message_with_tool_calls;

pub use tools::create_retry_messages;

pub use tools::execute_with_retry;

pub use tools::format_tool_error_for_model;

pub use tools::get_retryable_errors;

pub use tools::has_retryable_errors;

pub use tools::is_user_ask_tool_call;

pub use tools::parse_and_validate_tool_args;

pub use tools::parse_tool_args;

pub use tools::parse_user_ask_args;

pub use tools::respond_to_tool_call;

pub use tools::respond_to_tool_call_json;

pub use tools::serialize_user_ask_result;

pub use tools::sync_handler;

pub use tools::tool_result_message;

pub use tools::tool_result_message_json;

pub use tools::user_ask_result_choice;

pub use tools::user_ask_result_freeform;

pub use tools::user_ask_tool;

pub use tools::BoxFuture;

pub use tools::ParseResult;

pub use tools::ResponseExt;

pub use tools::RetryOptions;

pub use tools::ToolArgsError;

pub use tools::ToolBuilder;

pub use tools::ToolCallAccumulator;

pub use tools::ToolExecutionResult;

pub use tools::ToolHandler;

pub use tools::ToolRegistry;

pub use tools::TypedTool;

pub use tools::TypedToolCall;

pub use tools::UnknownToolError;

pub use tools::UserAskArgs;

pub use tools::UserAskOption;

pub use tools::UserAskResponse;

pub use tools::ValidateArgs;

pub use tools::USER_ASK_TOOL_NAME;

pub use tools::function_tool_from_type;

pub use tools::ToolSchema;

pub use types::Citation;

pub use types::MessageRole;

pub use generated::ImageData;

pub use generated::ImagePinResponse;

pub use generated::ImageRequest;

pub use generated::ImageResponse;

pub use generated::ImageResponseFormat;

pub use generated::ImageUsage;

pub use generated::RunsPendingToolCallV0;

pub use generated::RunsPendingToolsResponse;

pub use generated::SessionCreateRequest;

pub use generated::SessionListResponse;

pub use generated::SessionMessageCreateRequest;

pub use generated::SessionMessageResponse;

pub use generated::SessionResponse;

pub use generated::SessionWithMessagesResponse;

pub use generated::StateHandleCreateRequest;

pub use generated::StateHandleListResponse;

pub use generated::StateHandleResponse;

pub use generated::ToolCallId;

pub use generated::ToolName;

pub use identifiers::TierCode;

pub use workflow::ModelId;

pub use workflow::NodeErrorV0;

pub use workflow::NodeId;

pub use workflow::NodeStatusV0;

pub use workflow::PlanHash;

pub use workflow::ProviderId;

pub use workflow::RequestId;

pub use workflow::RunCostLineItemV0;

pub use workflow::RunCostSummaryV0;

pub use workflow::RunId;

pub use workflow::RunStatusV0;

pub use workflow::Sha256Hash;

pub use token_providers::CustomerTokenResponse;

Modules

generated

Generated types from OpenAPI spec. Run just generate-sdk-types to regenerate from api/openapi/api.yaml. Auto-generated types from OpenAPI spec.

testing

tools

Tool helpers for ergonomic tool use with the ModelRelay API.

wrapper_v1

Macros

tool_handler

Helper macro to create a tool handler from an async closure.

Structs

APIError

Structured error envelope returned by the API.

APIKey

Representation of an API key record.

AgentOptions

Options for Client::agent.

AgentResult

Result of running an agent.

AgentUsage

Usage tracking across an agent run.

ArtifactKey

Artifact key type for node outputs and run outputs.

AttemptRecord

Record of a single structured output attempt.

AuthClient

Async client for customer token operations.

BashPolicy

Semantic bash policy with safety rails.

BashResult

Result of a bash command execution.

BashTokens

Tokenized representation of a bash command string.

BatchError

Error details for an individual batch item.

BatchOptions

Batch execution options for /responses/batch.

BatchRequestItem

Request item for batch responses.

BatchResponse

Response payload for batch responses.

BatchResult

Result for a single batch item.

BatchUsage

Aggregate usage for batch responses.

ChainOptions

Options for chain() helper.

ChatOptions

Options for Client::chat and Client::ask.

Client

Async client for the ModelRelay API.

ClientBuilder

Builder for constructing a Client with explicit configuration.

CodeExecConfig

Code execution configuration.

Config

Configuration for the async ModelRelay client.

CustomerResponsesClient

Responses client scoped to a specific customer id.

CustomerScopedClient

Customer-scoped client that automatically applies the customer id header.

CustomerToken

Short-lived bearer token usable from browser/mobile clients.

CustomerTokenProvider

Token provider that mints customer bearer tokens using a secret key.

CustomerTokenProviderConfig

Configuration for CustomerTokenProvider.

CustomerTokenRequest

Request payload for POST /auth/customer-token.

DateTime

ISO 8601 combined date and time with time zone.

DefaultRetryHandler

Default retry handler that appends a simple error correction message.

FieldError

Field-level validation error returned by the API.

FileContent

File content within a content part.

FunctionCall

Function call details in a tool call.

FunctionCallDelta

Incremental function call data.

FunctionTool

Function tool definition.

GetOrCreateCustomerTokenRequest

Request to get or create a customer and mint a token.

HeaderEntry

HeaderList

Structured header/metadata list with validation.

HttpRequestMetrics

HTTP request latency and outcome.

ImagesClient

Client for image generation operations.

JSONSchemaFormat

JSON schema payload for structured outputs.

JoinCollectOptions

LLMNodeBuilder

ListSessionsOptions

Options for listing sessions.

ListStateHandlesOptions

Options for listing state handles.

LocalBashToolPack

LocalBashToolPack provides safe-by-default bash command execution.

LocalFSToolPack

LocalFSToolPack provides safe-by-default implementations of tools.v0 filesystem tools:

MapFanoutOptions

MetricsCallbacks

User-provided callbacks for emitting metrics without taking on a tracing dependency.

MimeType

IANA media type string (e.g., “image/png”, “application/pdf”).

Model

Model identifier (string wrapper).

NodeResultV0

Result of a completed node.

OutputFormat

Output format configuration (structured outputs).

ParallelOptions

Options for parallel() helper.

PayloadInfoV0

Metadata about a payload (node output or run outputs).

Plugin

PluginAgent

PluginAgentName

PluginCommand

PluginCommandName

PluginConverter

PluginConverterOptions

PluginGitHubRef

PluginId

PluginLoader

PluginLoaderOptions

PluginManifest

PluginOrchestrationError

PluginRunConfig

PluginRunError

PluginRunResult

PluginUrl

PluginsClient

PluginsClientOptions

PollUntilOptions

Configuration for polling with backoff.

RequestContext

Common request metadata shared by all telemetry events.

Response

Aggregated response returned by POST /responses.

ResponseBuilder

Builder for POST /responses (async).

ResponseOptions

Optional headers for POST /responses calls.

ResponseStreamAdapter

Adapter that yields only text deltas from a stream handle.

ResponsesClient

Async client for POST /responses.

RetryConfig

Retry/backoff configuration (defaults use 3 attempts + jittered exponential backoff).

RetryMetadata

Retry metadata surfaced on transport/API errors when retries were attempted.

RunEventEnvelope

Common envelope fields for all run events.

RunEventStreamHandlestreaming

RunEventV0

A run event with envelope metadata and payload.

RunsClient

RunsCreateOptions

RunsCreateResponse

RunsFanoutSubnodeOverride

RunsGetResponse

RunsModelOverrides

RunsToolCallV0

RunsToolResultItemV0

RunsToolResultsRequest

RunsToolResultsResponse

SecretKey

SessionsClient

Client for session operations.

SqlClient

Client for SQL validation operations.

SqlColumnInfo

SqlExecuteResult

SqlTableDescription

SqlTableInfo

SqlToolLoopBuilder

SqlToolLoopHandlers

SqlToolLoopOptions

SqlToolLoopResult

StateHandlesClient

Client for state handle operations.

StreamEvent

Single SSE event emitted by the streaming proxy.

StreamFirstTokenMetrics

Time from request start to the first streaming token/event.

StreamHandlestreaming

Streaming handle over NDJSON response events.

StreamTimeoutError

Typed error for streaming timeouts.

StructuredDecodeError

Error returned when structured output fails on first attempt (before retries).

StructuredExhaustedError

Error returned when all retry attempts are exhausted.

StructuredJSONEvent

Structured JSON event (parsed from NDJSON envelope).

StructuredJSONStreamstreaming

Helper over NDJSON streaming events to yield structured JSON payloads.

StructuredOptions

Options for structured output requests.

StructuredResult

Result of a successful structured output request.

Tier

TierCheckoutRequest

Request to create a tier checkout session (checkout-first flow). Stripe collects the customer’s email during checkout.

TierCheckoutSession

Tier checkout session response.

TierModel

A model with cost information in a tier. Customer prices are derived from model costs: price = cost * (1 + platformFeePercent/100).

TiersClient

Client for tier querying operations.

TokenUsageMetrics

Token usage surfaced once a request/stream finishes.

Tool

A tool available for the model to call.

ToolCall

A tool call made by the model.

ToolCallDelta

Incremental update to a tool call during streaming.

ToolChoice

Controls how the model responds to tool calls.

ToolResultItem

A tool result item for use with continuation helpers.

TransportError

Transport-level error (timeouts, DNS/TLS/connectivity).

Usage

Token usage metadata.

UsageSummary

Utc

The UTC time zone. This is the most efficient time zone when you don’t need the local time. It is also used as an offset (which is also a dummy type).

Uuid

A Universally Unique Identifier (UUID).

ValidationError

Structured validation/build error returned by the SDK.

ValidationIssue

A single field-level validation issue.

WorkflowIntentBuilder

WorkflowIntentCondition

Condition used by join.any/join.collect predicates.

WorkflowIntentInputDecl

Workflow input declaration.

WorkflowIntentNode

A node in the workflow DAG.

WorkflowIntentOutputRef

Reference to a workflow output.

WorkflowIntentSpec

Workflow specification.

WorkflowIntentToolExecution

Tool execution configuration for LLM nodes.

WorkflowIntentTransformValue

Transform value reference for transform.json nodes.

WorkflowValidationError

Typed workflow validation error surfaced by the SDK.

WorkflowValidationIssue

Workflow semantic validation error returned by the API compiler (/workflows/compile).

WorkflowsClient

WorkflowsCompileResponse

XSearchConfig

X/Twitter search configuration.

Enums

ApiKey

BatchStatus

Status for a batch item.

ContentPart

Content part within a message.

EnvelopeVersion

Envelope version for run events. Schema specifies const “v2”.

Error

Unified error type surfaced by the SDK.

InputItem

Input item sent to /responses.

LocalToolError

Error type for local tool pack operations.

NodeTypeV1

Node type within a workflow.v1.

OrchestrationMode

OutputFormatKind

Supported output format types.

OutputItem

Output item returned by /responses.

PluginError

PluginOrchestrationErrorCode

PluginToolName

PollResult

Outcome of a polling attempt.

PriceInterval

Billing interval for a tier.

RunEventPayload

Event-specific payload data.

RunEventTypeV0

Run event type discriminator.

StopReason

Stop reason returned by the backend and surfaced by /responses.

StreamEventKind

High-level streaming event kinds emitted by the API.

StreamTimeoutKind

Which streaming timeout triggered.

StructuredError

Unified error type for structured output operations.

StructuredErrorKind

Specific kind of structured output error.

StructuredRecordKind

Kind of structured record.

SubscriptionStatusKind

Subscription status for billing integrations.

ToolChoiceType

Tool choice type.

ToolType

Tool type identifiers.

TransportErrorKind

Broad transport error kinds for classification.

WorkflowIntentKind

Workflow specification kind.

WorkflowIntentNodeType

Node type within a workflow.

WorkflowIntentToolExecutionMode

Tool execution mode for LLM nodes.

WorkflowIntentToolRef

Tool reference for workflow.

WorkflowsCompileResult

Constants

CUSTOMER_ID_HEADER

HTTP header name for customer-attributed requests.

DEFAULT_BASE_URL

Default API base URL.

DEFAULT_CONNECT_TIMEOUT

Default connection timeout (5 seconds).

DEFAULT_MAX_TURNS

Default maximum turns for agent loops.

DEFAULT_REQUEST_TIMEOUT

Default request timeout (60 seconds).

LLM_TEXT_OUTPUT

JSON pointer to extract text content from an LLM response output. Points to: output[0].content[0].text

LLM_USER_MESSAGE_TEXT

JSON pointer to inject text into the user message of an LLM request. Points to: input[1].content[0].text (index 1 assumes a system message at index 0). The pointer is relative to the request object (not the full node input).

MAX_STATE_HANDLE_TTL_SECONDS

Maximum allowed TTL for a state handle (1 year in seconds).

NO_TURN_LIMIT

Use this for max_turns to disable the turn limit. Use with caution as this can lead to infinite loops and runaway API costs.

REQUEST_ID_HEADER

HTTP header name for request ID tracing.

RUN_EVENT_V0_SCHEMA_JSON

JSON Schema for run_event.v2 events.

Traits

MessageRoleExt

Extension trait for MessageRole providing convenience methods.

RetryHandler

Handler for customizing retry behavior on validation failures.

TokenProvider

Trait for token providers that supply bearer tokens for API requests.

Functions

chain

Creates a sequential workflow where each step depends on the previous one. Edges are automatically wired based on order.

get_all_tool_calls_from_response

Extracts all tool calls from a response.

llm

Creates a standalone LLM node for use with chain() and parallel().

new_local_bash_tools

Creates a ToolRegistry with the LocalBashToolPack registered.

new_local_fs_tools

Creates a ToolRegistry with the LocalFSToolPack registered.

output_format_from_type

Generates an OutputFormat with automatic JSON schema from a type.

parallel

Creates a parallel workflow where all steps run concurrently, then join. Edges are automatically wired to a join.all node.

poll_until

Poll until the closure returns a value or the deadline is exceeded.

run_node_ref

Creates a reference string for a node within a run.

tokenize_bash

Tokenize a bash command string with lightweight detection and normalization.

with_bash_allow_env_vars

Only passes the specified environment variables to the command.

with_bash_hard_max_output_bytes

Sets the hard cap for output bytes. This is the absolute maximum regardless of requested limits.

with_bash_inherit_env

Inherits all environment variables from the parent process.

with_bash_max_output_bytes

Sets the soft limit for output bytes. Output beyond this limit will be truncated.

with_bash_policy

Sets the bash policy for command execution.

with_bash_timeout

Sets the timeout for command execution.

with_local_fs_hard_max_list_entries

WithLocalFSHardMaxListEntries changes the hard cap for fs.list_files max_entries.

with_local_fs_hard_max_read_bytes

WithLocalFSHardMaxReadBytes changes the hard cap for fs.read_file max_bytes.

with_local_fs_hard_max_search_matches

WithLocalFSHardMaxSearchMatches changes the hard cap for fs.search max_matches.

with_local_fs_ignore_dirs

WithLocalFSIgnoreDirs configures directory names to skip during fs.list_files and fs.search. Names are matched by path segment (e.g. “.git” skips any “.git” directory anywhere under root).

with_local_fs_max_list_entries

WithLocalFSMaxListEntries changes the default max_entries when the tool call does not specify max_entries.

with_local_fs_max_read_bytes

WithLocalFSMaxReadBytes changes the default max_bytes when the tool call does not specify max_bytes.

with_local_fs_max_search_bytes

WithLocalFSMaxSearchBytes sets a per-file byte limit for the fs.search implementation.

with_local_fs_max_search_matches

WithLocalFSMaxSearchMatches changes the default max_matches when the tool call does not specify max_matches.

with_local_fs_search_timeout

WithLocalFSSearchTimeout configures the timeout for fs.search.

workflow

Alias for workflow_intent() with a cleaner name.

workflow_intent

Type Aliases

IntentKind

IntentSpec

LocalBashOption

Configuration options for the local bash tool pack.

LocalFSOption

Configuration options for the local filesystem tool pack.

SqlRow