@tanstack/ai-anthropic 0.0.1

package/src/text/text-provider-options.ts

@@ -0,0 +1,205 @@
+import type {
+  BetaContextManagementConfig,
+  BetaToolChoiceAny,
+  BetaToolChoiceAuto,
+  BetaToolChoiceTool,
+} from '@anthropic-ai/sdk/resources/beta/messages/messages'
+import type { AnthropicTool } from '../tools'
+import type {
+  MessageParam,
+  TextBlockParam,
+} from '@anthropic-ai/sdk/resources/messages'
+
+export interface AnthropicContainerOptions {
+  /**
+   * Container identifier for reuse across requests.
+   * Container parameters with skills to be loaded.
+   */
+  container?: {
+    id: string | null
+    /**
+     * List of skills to load into the container
+     */
+    skills: Array<{
+      /**
+       * Between 1-64 characters
+       */
+      skill_id: string
+
+      type: 'anthropic' | 'custom'
+      /**
+       * Skill version or latest by default
+       */
+      version?: string
+    }> | null
+  } | null
+}
+
+export interface AnthropicContextManagementOptions {
+  /**
+   * Context management configuration.
+
+This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not.
+   */
+  context_management?: BetaContextManagementConfig | null
+}
+
+export interface AnthropicMCPOptions {
+  /**
+   * MCP servers to be utilized in this request
+   * Maximum of 20 servers
+   */
+  mcp_servers?: Array<MCPServer>
+}
+
+export interface AnthropicServiceTierOptions {
+  /**
+   * Determines whether to use priority capacity (if available) or standard capacity for this request.
+   */
+  service_tier?: 'auto' | 'standard_only'
+}
+
+export interface AnthropicStopSequencesOptions {
+  /**
+   * Custom text sequences that will cause the model to stop generating.
+
+Anthropic models will normally stop when they have naturally completed their turn, which will result in a response stop_reason of "end_turn".
+
+If you want the model to stop generating when it encounters custom strings of text, you can use the stop_sequences parameter. If the model encounters one of the custom sequences, the response stop_reason value will be "stop_sequence" and the response stop_sequence value will contain the matched stop sequence.
+   */
+  stop_sequences?: Array<string>
+}
+
+export interface AnthropicThinkingOptions {
+  /**
+     * Configuration for enabling Claude's extended thinking.
+
+When enabled, responses include thinking content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your max_tokens limit.
+     */
+  thinking?:
+    | {
+        /**
+* Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality.
+
+Must be ≥1024 and less than max_tokens
+*/
+        budget_tokens: number
+
+        type: 'enabled'
+      }
+    | {
+        type: 'disabled'
+      }
+}
+
+export interface AnthropicToolChoiceOptions {
+  tool_choice?: BetaToolChoiceAny | BetaToolChoiceTool | BetaToolChoiceAuto
+}
+
+export interface AnthropicSamplingOptions {
+  /**
+   * Only sample from the top K options for each subsequent token.
+
+Used to remove "long tail" low probability responses.
+Recommended for advanced use cases only. You usually only need to use temperature.
+
+Required range: x >= 0
+   */
+  top_k?: number
+}
+
+export type ExternalTextProviderOptions = AnthropicContainerOptions &
+  AnthropicContextManagementOptions &
+  AnthropicMCPOptions &
+  AnthropicServiceTierOptions &
+  AnthropicStopSequencesOptions &
+  AnthropicThinkingOptions &
+  AnthropicToolChoiceOptions &
+  AnthropicSamplingOptions
+
+export interface InternalTextProviderOptions
+  extends ExternalTextProviderOptions {
+  model: string
+
+  messages: Array<MessageParam>
+
+  /**
+   * The maximum number of tokens to generate before stopping.  This parameter only specifies the absolute maximum number of tokens to generate.
+   * Range x >= 1.
+   */
+  max_tokens: number
+  /**
+   * Whether to incrementally stream the response using server-sent events.
+   */
+  stream?: boolean
+  /**
+    * stem prompt.
+ 
+ A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role.
+    */
+  system?: string | Array<TextBlockParam>
+  /**
+   * Amount of randomness injected into the response.
+   * Either use this or top_p, but not both.
+   * Defaults to 1.0. Ranges from 0.0 to 1.0. Use temperature closer to 0.0 for analytical / multiple choice, and closer to 1.0 for creative and generative tasks.
+   * @default 1.0
+   */
+  temperature?: number
+
+  tools?: Array<AnthropicTool>
+
+  /**
+   * Use nucleus sampling.
+
+In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by top_p. You should either alter temperature or top_p, but not both.
+   */
+  top_p?: number
+}
+
+const validateTopPandTemperature = (options: InternalTextProviderOptions) => {
+  if (options.top_p !== undefined && options.temperature !== undefined) {
+    throw new Error('You should either set top_p or temperature, but not both.')
+  }
+}
+
+export interface CacheControl {
+  type: 'ephemeral'
+  ttl: '5m' | '1h'
+}
+
+const validateThinking = (options: InternalTextProviderOptions) => {
+  const thinking = options.thinking
+  if (thinking && thinking.type === 'enabled') {
+    if (thinking.budget_tokens < 1024) {
+      throw new Error('thinking.budget_tokens must be at least 1024.')
+    }
+    if (thinking.budget_tokens >= options.max_tokens) {
+      throw new Error('thinking.budget_tokens must be less than max_tokens.')
+    }
+  }
+}
+
+interface MCPServer {
+  name: string
+  url: string
+  type: 'url'
+  authorization_token?: string | null
+  tool_configuration: {
+    allowed_tools?: Array<string> | null
+    enabled?: boolean | null
+  } | null
+}
+
+const validateMaxTokens = (options: InternalTextProviderOptions) => {
+  if (options.max_tokens < 1) {
+    throw new Error('max_tokens must be at least 1.')
+  }
+}
+
+export const validateTextProviderOptions = (
+  options: InternalTextProviderOptions,
+) => {
+  validateTopPandTemperature(options)
+  validateThinking(options)
+  validateMaxTokens(options)
+}

package/src/tools/bash-tool.ts

@@ -0,0 +1,19 @@
+import type {
+  BetaToolBash20241022,
+  BetaToolBash20250124,
+} from '@anthropic-ai/sdk/resources/beta'
+import type { Tool } from '@tanstack/ai'
+
+export type BashTool = BetaToolBash20241022 | BetaToolBash20250124
+
+export function convertBashToolToAdapterFormat(tool: Tool): BashTool {
+  const metadata = tool.metadata as BashTool
+  return metadata
+}
+export function bashTool(config: BashTool): Tool {
+  return {
+    name: 'bash',
+    description: '',
+    metadata: config,
+  }
+}

package/src/tools/code-execution-tool.ts

@@ -0,0 +1,24 @@
+import type {
+  BetaCodeExecutionTool20250522,
+  BetaCodeExecutionTool20250825,
+} from '@anthropic-ai/sdk/resources/beta'
+import type { Tool } from '@tanstack/ai'
+
+export type CodeExecutionTool =
+  | BetaCodeExecutionTool20250522
+  | BetaCodeExecutionTool20250825
+
+export function convertCodeExecutionToolToAdapterFormat(
+  tool: Tool,
+): CodeExecutionTool {
+  const metadata = tool.metadata as CodeExecutionTool
+  return metadata
+}
+
+export function codeExecutionTool(config: CodeExecutionTool): Tool {
+  return {
+    name: 'code_execution',
+    description: '',
+    metadata: config,
+  }
+}

package/src/tools/computer-use-tool.ts

@@ -0,0 +1,24 @@
+import type {
+  BetaToolComputerUse20241022,
+  BetaToolComputerUse20250124,
+} from '@anthropic-ai/sdk/resources/beta'
+import type { Tool } from '@tanstack/ai'
+
+export type ComputerUseTool =
+  | BetaToolComputerUse20241022
+  | BetaToolComputerUse20250124
+
+export function convertComputerUseToolToAdapterFormat(
+  tool: Tool,
+): ComputerUseTool {
+  const metadata = tool.metadata as ComputerUseTool
+  return metadata
+}
+
+export function computerUseTool(config: ComputerUseTool): Tool {
+  return {
+    name: 'computer',
+    description: '',
+    metadata: config,
+  }
+}

package/src/tools/custom-tool.ts

@@ -0,0 +1,64 @@
+import { convertZodToJsonSchema } from '@tanstack/ai'
+import type { Tool } from '@tanstack/ai'
+import type { z } from 'zod'
+import type { CacheControl } from '../text/text-provider-options'
+
+export interface CustomTool {
+  /**
+   * The name of the tool.
+   */
+  name: string
+  type: 'custom'
+  /**
+   * A brief description of what the tool does. Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema.
+   */
+  description: string
+  /**
+   * This defines the shape of the input that your tool accepts and that the model will produce.
+   */
+  input_schema: {
+    type: 'object'
+    properties: Record<string, any> | null
+    required?: Array<string> | null
+  }
+
+  cache_control?: CacheControl | null
+}
+
+export function convertCustomToolToAdapterFormat(tool: Tool): CustomTool {
+  const metadata =
+    (tool.metadata as { cacheControl?: CacheControl | null } | undefined) || {}
+
+  // Convert Zod schema to JSON Schema
+  const jsonSchema = convertZodToJsonSchema(tool.inputSchema)
+
+  const inputSchema = {
+    type: 'object' as const,
+    properties: jsonSchema?.properties || null,
+    required: jsonSchema?.required || null,
+  }
+
+  return {
+    name: tool.name,
+    type: 'custom',
+    description: tool.description,
+    input_schema: inputSchema,
+    cache_control: metadata.cacheControl || null,
+  }
+}
+
+export function customTool(
+  name: string,
+  description: string,
+  inputSchema: z.ZodType,
+  cacheControl?: CacheControl | null,
+): Tool {
+  return {
+    name,
+    description,
+    inputSchema,
+    metadata: {
+      cacheControl,
+    },
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,30 @@
+import type { BashTool } from './bash-tool'
+import type { CodeExecutionTool } from './code-execution-tool'
+import type { ComputerUseTool } from './computer-use-tool'
+import type { CustomTool } from './custom-tool'
+import type { MemoryTool } from './memory-tool'
+import type { TextEditorTool } from './text-editor-tool'
+import type { WebFetchTool } from './web-fetch-tool'
+import type { WebSearchTool } from './web-search-tool'
+
+export type AnthropicTool =
+  | BashTool
+  | CodeExecutionTool
+  | ComputerUseTool
+  | CustomTool
+  | MemoryTool
+  | TextEditorTool
+  | WebFetchTool
+  | WebSearchTool
+
+// Export individual tool types
+export type {
+  // BashTool,
+  // CodeExecutionTool,
+  // ComputerUseTool,
+  CustomTool,
+  // MemoryTool,
+  // TextEditorTool,
+  // WebFetchTool,
+  // WebSearchTool,
+}

package/src/tools/memory-tool.ts

@@ -0,0 +1,20 @@
+import type { BetaMemoryTool20250818 } from '@anthropic-ai/sdk/resources/beta'
+import type { Tool } from '@tanstack/ai'
+
+export type MemoryTool = BetaMemoryTool20250818
+
+export function convertMemoryToolToAdapterFormat(tool: Tool): MemoryTool {
+  const metadata = tool.metadata as Omit<MemoryTool, 'type'>
+  return {
+    type: 'memory_20250818',
+    ...metadata,
+  }
+}
+
+export function memoryTool(config?: MemoryTool): Tool {
+  return {
+    name: 'memory',
+    description: '',
+    metadata: config,
+  }
+}

package/src/tools/text-editor-tool.ts

@@ -0,0 +1,28 @@
+import type {
+  ToolTextEditor20250124,
+  ToolTextEditor20250429,
+  ToolTextEditor20250728,
+} from '@anthropic-ai/sdk/resources/messages'
+import type { Tool } from '@tanstack/ai'
+
+export type TextEditorTool =
+  | ToolTextEditor20250124
+  | ToolTextEditor20250429
+  | ToolTextEditor20250728
+
+export function convertTextEditorToolToAdapterFormat(
+  tool: Tool,
+): TextEditorTool {
+  const metadata = tool.metadata as TextEditorTool
+  return {
+    ...metadata,
+  }
+}
+
+export function textEditorTool<T extends TextEditorTool>(config: T): Tool {
+  return {
+    name: 'str_replace_editor',
+    description: '',
+    metadata: config,
+  }
+}

package/src/tools/tool-converter.ts

@@ -0,0 +1,61 @@
+import { convertBashToolToAdapterFormat } from './bash-tool'
+import { convertCodeExecutionToolToAdapterFormat } from './code-execution-tool'
+import { convertComputerUseToolToAdapterFormat } from './computer-use-tool'
+import { convertCustomToolToAdapterFormat } from './custom-tool'
+import { convertMemoryToolToAdapterFormat } from './memory-tool'
+import { convertTextEditorToolToAdapterFormat } from './text-editor-tool'
+import { convertWebFetchToolToAdapterFormat } from './web-fetch-tool'
+import { convertWebSearchToolToAdapterFormat } from './web-search-tool'
+import type { AnthropicTool } from '.'
+import type { Tool } from '@tanstack/ai'
+
+/**
+ * Converts standard Tool format to Anthropic-specific tool format
+ *
+ * @param tools - Array of standard Tool objects
+ * @returns Array of Anthropic-specific tool definitions
+ *
+ * @example
+ * ```typescript
+ * const tools: Tool[] = [{
+ *   type: "function",
+ *   function: {
+ *     name: "get_weather",
+ *     description: "Get weather for a location",
+ *     parameters: {
+ *       type: "object",
+ *       properties: { location: { type: "string" } },
+ *       required: ["location"]
+ *     }
+ *   }
+ * }];
+ *
+ * const anthropicTools = convertToolsToProviderFormat(tools);
+ * ```
+ */
+export function convertToolsToProviderFormat<TTool extends Tool>(
+  tools: Array<TTool>,
+): Array<AnthropicTool> {
+  return tools.map((tool) => {
+    const name = tool.name
+
+    switch (name) {
+      case 'bash':
+        return convertBashToolToAdapterFormat(tool)
+      case 'code_execution':
+        return convertCodeExecutionToolToAdapterFormat(tool)
+      case 'computer':
+        return convertComputerUseToolToAdapterFormat(tool)
+      case 'memory':
+        return convertMemoryToolToAdapterFormat(tool)
+      case 'str_replace_editor':
+        return convertTextEditorToolToAdapterFormat(tool)
+      case 'web_fetch':
+        return convertWebFetchToolToAdapterFormat(tool)
+      case 'web_search':
+        return convertWebSearchToolToAdapterFormat(tool)
+      default:
+        return convertCustomToolToAdapterFormat(tool)
+    }
+  })
+}

package/src/tools/web-fetch-tool.ts

@@ -0,0 +1,23 @@
+import type { BetaWebFetchTool20250910 } from '@anthropic-ai/sdk/resources/beta'
+import type { Tool } from '@tanstack/ai'
+
+export type WebFetchTool = BetaWebFetchTool20250910
+
+export function convertWebFetchToolToAdapterFormat(tool: Tool): WebFetchTool {
+  const metadata = tool.metadata as Omit<WebFetchTool, 'type' | 'name'>
+  return {
+    name: 'web_fetch',
+    type: 'web_fetch_20250910',
+    ...metadata,
+  }
+}
+
+export function webFetchTool(
+  config?: Omit<WebFetchTool, 'type' | 'name'>,
+): Tool {
+  return {
+    name: 'web_fetch',
+    description: '',
+    metadata: config,
+  }
+}

package/src/tools/web-search-tool.ts

@@ -0,0 +1,81 @@
+import type { WebSearchTool20250305 } from '@anthropic-ai/sdk/resources/messages'
+import type { CacheControl } from '../text/text-provider-options'
+import type { Tool } from '@tanstack/ai'
+
+export type WebSearchTool = WebSearchTool20250305
+
+const validateDomains = (tool: WebSearchTool) => {
+  if (tool.allowed_domains && tool.blocked_domains) {
+    throw new Error(
+      'allowed_domains and blocked_domains cannot be used together.',
+    )
+  }
+}
+
+const validateUserLocation = (tool: WebSearchTool) => {
+  const userLocation = tool.user_location
+  if (userLocation) {
+    if (
+      userLocation.city &&
+      (userLocation.city.length < 1 || userLocation.city.length > 255)
+    ) {
+      throw new Error(
+        'user_location.city must be between 1 and 255 characters.',
+      )
+    }
+    if (userLocation.country && userLocation.country.length !== 2) {
+      throw new Error('user_location.country must be exactly 2 characters.')
+    }
+    if (
+      userLocation.region &&
+      (userLocation.region.length < 1 || userLocation.region.length > 255)
+    ) {
+      throw new Error(
+        'user_location.region must be between 1 and 255 characters.',
+      )
+    }
+    if (
+      userLocation.timezone &&
+      (userLocation.timezone.length < 1 || userLocation.timezone.length > 255)
+    ) {
+      throw new Error(
+        'user_location.timezone must be between 1 and 255 characters.',
+      )
+    }
+  }
+}
+
+export function convertWebSearchToolToAdapterFormat(tool: Tool): WebSearchTool {
+  const metadata = tool.metadata as {
+    allowedDomains?: Array<string> | null
+    blockedDomains?: Array<string> | null
+    maxUses?: number | null
+    userLocation?: {
+      type: 'approximate'
+      city?: string | null
+      country?: string | null
+      region?: string | null
+      timezone?: string | null
+    } | null
+    cacheControl?: CacheControl | null
+  }
+  return {
+    name: 'web_search',
+    type: 'web_search_20250305',
+    allowed_domains: metadata.allowedDomains,
+    blocked_domains: metadata.blockedDomains,
+    max_uses: metadata.maxUses,
+    user_location: metadata.userLocation,
+    cache_control: metadata.cacheControl || null,
+  }
+}
+
+export function webSearchTool(config: WebSearchTool): Tool {
+  validateDomains(config)
+  validateUserLocation(config)
+  return {
+    name: 'web_search',
+    description: '',
+    metadata: config,
+  }
+}