feat: first take of adding caching support

src/AnthropicClient/Json/JsonSerializationOptions.cs

@@ -17,6 +17,7 @@ static class JsonSerializationOptions
       new EventDataConverter(),
       new ContentDeltaConverter(),
       new JsonStringEnumConverter(),
+      new MessageRequestConverter(),
     },
     DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
   };

src/AnthropicClient/Json/MessageRequestConverter.cs

@@ -0,0 +1,19 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+using AnthropicClient.Models;
+
+namespace AnthropicClient.Json;
+
+class MessageRequestConverter : JsonConverter<MessageRequest>
+{
+  public override MessageRequest Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+  {
+    return JsonSerializer.Deserialize<MessageRequest>(ref reader, options)!;
+  }
+
+  public override void Write(Utf8JsonWriter writer, MessageRequest value, JsonSerializerOptions options)
+  {
+    throw new NotImplementedException();
+  }
+}

src/AnthropicClient/Models/BaseMessageRequest.cs

@@ -19,6 +19,11 @@ public abstract class BaseMessageRequest
   /// </summary>
   public string? System { get; init; } = null;
 
+  /// <summary>
+  /// Gets the messages to send to the model.
+  /// </summary>
+  public List<TextContent>? SystemMessages { get; init; } = null;
+
   /// <summary>
   /// Gets the messages to send to the model.
   /// </summary>
@@ -75,40 +80,20 @@ public abstract class BaseMessageRequest
   [JsonConstructor]
   internal BaseMessageRequest() { }
   
-  /// <summary>
+  private BaseMessageRequest(
-  /// Initializes a new instance of the <see cref="BaseMessageRequest"/> class.
-  /// </summary>
-  /// <param name="model">The model ID to use for the request.</param>
-  /// <param name="messages">The messages to send to the model.</param>
-  /// <param name="maxTokens">The maximum number of tokens to generate.</param>
-  /// <param name="system">The system ID to use for the request.</param>
-  /// <param name="metadata">The metadata to include with the request.</param>
-  /// <param name="temperature">The temperature to use for the request.</param>
-  /// <param name="topK">The top-K value to use for the request.</param>
-  /// <param name="topP">The top-P value to use for the request.</param>
-  /// <param name="toolChoice">The tool choice mode to use for the request.</param>
-  /// <param name="tools">The tools to use for the request.</param>
-  /// <param name="stream">A value indicating whether the message should be streamed.</param>
-  /// <param name="stopSequences">The prompt stop sequences.</param>
-  /// <exception cref="ArgumentException">Thrown when the model ID is invalid.</exception>
-  /// <exception cref="ArgumentNullException">Thrown when the model or messages is null.</exception>
-  /// <exception cref="ArgumentException">Thrown when the messages contain no messages.</exception>
-  /// <exception cref="ArgumentException">Thrown when the max tokens is less than one.</exception>
-  /// <exception cref="ArgumentException">Thrown when the temperature is less than zero or greater than one.</exception>
-  /// <returns>A new instance of the <see cref="BaseMessageRequest"/> class.</returns>
-  protected BaseMessageRequest(
     string model,
     List<Message> messages,
-    int maxTokens = 1024,
+    int maxTokens,
-    string? system = null,
+    string? system,
-    Dictionary<string, object>? metadata = null,
+    List<TextContent>? systemMessages,
-    decimal temperature = 0.0m,
+    Dictionary<string, object>? metadata,
-    int? topK = null,
+    decimal temperature,
-    decimal? topP = null,
+    int? topK,
-    ToolChoice? toolChoice = null,
+    decimal? topP,
-    List<Tool>? tools = null,
+    ToolChoice? toolChoice,
-    bool stream = false,
+    List<Tool>? tools,
-    List<string>? stopSequences = null
+    bool stream,
+    List<string>? stopSequences
   )
   {
     ArgumentValidator.ThrowIfNull(model, nameof(model));
@@ -138,6 +123,7 @@ public abstract class BaseMessageRequest
     Messages = messages;
     MaxTokens = maxTokens;
     System = system;
+    SystemMessages = systemMessages;
     Metadata = metadata;
     Temperature = temperature;
     TopK = topK;
@@ -147,4 +133,108 @@ public abstract class BaseMessageRequest
     Stream = stream;
     StopSequences = stopSequences ?? [];
   }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="BaseMessageRequest"/> class.
+  /// </summary>
+  /// <param name="model">The model ID to use for the request.</param>
+  /// <param name="messages">The messages to send to the model.</param>
+  /// <param name="maxTokens">The maximum number of tokens to generate.</param>
+  /// <param name="system">The system prompt to use for the request.</param>
+  /// <param name="metadata">The metadata to include with the request.</param>
+  /// <param name="temperature">The temperature to use for the request.</param>
+  /// <param name="topK">The top-K value to use for the request.</param>
+  /// <param name="topP">The top-P value to use for the request.</param>
+  /// <param name="toolChoice">The tool choice mode to use for the request.</param>
+  /// <param name="tools">The tools to use for the request.</param>
+  /// <param name="stream">A value indicating whether the message should be streamed.</param>
+  /// <param name="stopSequences">The prompt stop sequences.</param>
+  /// <exception cref="ArgumentException">Thrown when the model ID is invalid.</exception>
+  /// <exception cref="ArgumentNullException">Thrown when the model or messages is null.</exception>
+  /// <exception cref="ArgumentException">Thrown when the messages contain no messages.</exception>
+  /// <exception cref="ArgumentException">Thrown when the max tokens is less than one.</exception>
+  /// <exception cref="ArgumentException">Thrown when the temperature is less than zero or greater than one.</exception>
+  /// <returns>A new instance of the <see cref="BaseMessageRequest"/> class.</returns>
+  protected BaseMessageRequest(
+    string model,
+    List<Message> messages,
+    int maxTokens = 1024,
+    string? system = null,
+    Dictionary<string, object>? metadata = null,
+    decimal temperature = 0.0m,
+    int? topK = null,
+    decimal? topP = null,
+    ToolChoice? toolChoice = null,
+    List<Tool>? tools = null,
+    bool stream = false,
+    List<string>? stopSequences = null
+  ) : this(
+    model,
+    messages,
+    maxTokens,
+    system,
+    null,
+    metadata,
+    temperature,
+    topK,
+    topP,
+    toolChoice,
+    tools,
+    stream,
+    stopSequences
+  )
+  {
+  }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="BaseMessageRequest"/> class.
+  /// </summary>
+  /// <param name="model">The model ID to use for the request.</param>
+  /// <param name="messages">The messages to send to the model.</param>
+  /// <param name="maxTokens">The maximum number of tokens to generate.</param>
+  /// <param name="systemMessages">The system messages to send to the model to be used as the system prompt.</param>
+  /// <param name="metadata">The metadata to include with the request.</param>
+  /// <param name="temperature">The temperature to use for the request.</param>
+  /// <param name="topK">The top-K value to use for the request.</param>
+  /// <param name="topP">The top-P value to use for the request.</param>
+  /// <param name="toolChoice">The tool choice mode to use for the request.</param>
+  /// <param name="tools">The tools to use for the request.</param>
+  /// <param name="stream">A value indicating whether the message should be streamed.</param>
+  /// <param name="stopSequences">The prompt stop sequences.</param>
+  /// <exception cref="ArgumentException">Thrown when the model ID is invalid.</exception>
+  /// <exception cref="ArgumentNullException">Thrown when the model or messages is null.</exception>
+  /// <exception cref="ArgumentException">Thrown when the messages contain no messages.</exception>
+  /// <exception cref="ArgumentException">Thrown when the max tokens is less than one.</exception>
+  /// <exception cref="ArgumentException">Thrown when the temperature is less than zero or greater than one.</exception>
+  /// <returns>A new instance of the <see cref="BaseMessageRequest"/> class.</returns>
+  protected BaseMessageRequest(
+    string model,
+    List<Message> messages,
+    int maxTokens = 1024,
+    List<TextContent>? systemMessages = null,
+    Dictionary<string, object>? metadata = null,
+    decimal temperature = 0.0m,
+    int? topK = null,
+    decimal? topP = null,
+    ToolChoice? toolChoice = null,
+    List<Tool>? tools = null,
+    bool stream = false,
+    List<string>? stopSequences = null
+  ) : this(
+    model,
+    messages,
+    maxTokens,
+    null,
+    systemMessages,
+    metadata,
+    temperature,
+    topK,
+    topP,
+    toolChoice,
+    tools,
+    stream,
+    stopSequences
+  )
+  {
+  }
 }

src/AnthropicClient/Models/CacheControl.cs

@@ -0,0 +1,27 @@
+using AnthropicClient.Utils;
+
+namespace AnthropicClient.Models;
+
+/// <summary>
+/// Represents the cache control to be used for content.
+/// </summary>
+public class CacheControl
+{ 
+  /// <summary>
+  /// Gets the type of the cache control.
+  /// </summary>
+  public string Type { get; init; } = string.Empty;
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="CacheControl"/> class.
+  /// </summary>
+  /// <param name="type">The type of the cache control.</param>
+  /// <returns>A new instance of the <see cref="CacheControl"/> class.</returns>
+  /// <exception cref="ArgumentException">Thrown when the type is null or whitespace.</exception>
+  public CacheControl(string type)
+  {
+    ArgumentValidator.ThrowIfNullOrWhitespace(type, nameof(type));
+
+    Type = type;
+  }
+}

src/AnthropicClient/Models/CacheControlType.cs

@@ -0,0 +1,12 @@
+namespace AnthropicClient.Models;
+
+/// <summary>
+/// Provides constants for cache control types.
+/// </summary>
+public static class CacheControlType
+{
+  /// <summary>
+  /// The cache control type for an ephemeral cache.
+  /// </summary>
+  public const string Ephemeral = "ephemeral";
+}

src/AnthropicClient/Models/Content.cs

@@ -12,6 +12,12 @@ public abstract class Content
   /// </summary>
   public string Type { get; init; } = string.Empty;
   
+  /// <summary>
+  /// Gets the cache control to be used for the content.
+  /// </summary>
+  [JsonPropertyName("cache_control")]
+  public CacheControl? CacheControl { get; init; }
+
   [JsonConstructor]
   internal Content()
   {
@@ -26,4 +32,16 @@ public abstract class Content
   {
     Type = type;
   }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="Content"/> class.
+  /// </summary>
+  /// <param name="type">The type of the content.</param>
+  /// <param name="cacheControl">The cache control to be used for the content.</param>
+  /// <returns>A new instance of the <see cref="Content"/> class.</returns>
+  protected Content(string type, CacheControl cacheControl)
+  {
+    Type = type;
+    CacheControl = cacheControl;
+  }
 }

src/AnthropicClient/Models/ImageContent.cs

@@ -33,4 +33,20 @@ public class ImageContent : Content
 
     Source = new(mediaType, data);
   }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="ImageContent"/> class.
+  /// </summary>
+  /// <param name="mediaType">The media type of the image.</param>
+  /// <param name="data">The data of the image.</param>
+  /// <param name="cacheControl">The cache control to be used for the content.</param>
+  /// <returns>A new instance of the <see cref="ImageContent"/> class.</returns>
+  /// <exception cref="ArgumentNullException">Thrown when the media type, data, or cache control is null.</exception>
+  public ImageContent(string mediaType, string data, CacheControl cacheControl) : base(ContentType.Image, cacheControl)
+  {
+    ArgumentValidator.ThrowIfNull(mediaType, nameof(mediaType));
+    ArgumentValidator.ThrowIfNull(data, nameof(data));
+
+    Source = new(mediaType, data);
+  }
 }

src/AnthropicClient/Models/TextContent.cs

@@ -31,4 +31,18 @@ public class TextContent : Content
 
     Text = text;
   }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="TextContent"/> class.
+  /// </summary>
+  /// <param name="text">The text of the content.</param>
+  /// <param name="cacheControl">The cache control to be used for the content.</param>
+  /// <returns>A new instance of the <see cref="TextContent"/> class.</returns>
+  /// <exception cref="ArgumentNullException">Thrown when the text or cache control is null.</exception>
+  public TextContent(string text, CacheControl cacheControl) : base(ContentType.Text, cacheControl)
+  {
+    ArgumentValidator.ThrowIfNull(text, nameof(text));
+
+    Text = text;
+  }
 }

src/AnthropicClient/Models/Tool.cs

@@ -55,6 +55,11 @@ public class Tool
   [JsonIgnore]
   public AnthropicFunction Function { get; }
 
+  /// <summary>
+  /// Gets or sets the cache control to be used for the tool.
+  /// </summary>
+  public CacheControl? CacheControl { get; set; }
+
   /// <summary>
   /// Gets the display name of the tool.
   /// </summary>
@@ -73,7 +78,7 @@ public class Tool
     DisplayName = string.Empty;
   }
 
-  internal Tool(string name, string description, AnthropicFunction function)
+  internal Tool(string name, string description, AnthropicFunction function, CacheControl? cacheControl = null)
   {
     ArgumentValidator.ThrowIfNullOrWhitespace(name, nameof(name));
     ArgumentValidator.ThrowIfNullOrWhitespace(description, nameof(description));
@@ -89,6 +94,7 @@ public class Tool
     Description = description;
     Function = function;
     InputSchema = JsonSchemaGenerator.GenerateInputSchema(function);
+    CacheControl = cacheControl;
   }
 
   /// <summary>
@@ -99,7 +105,7 @@ public class Tool
   /// <exception cref="ArgumentNullException">Thrown when the function of the tool is null.</exception>
   /// <returns>The created tool as instance of <see cref="Tool"/>.</returns>
   /// <remarks>The implementation of <see cref="ITool"/> must have a parameterless constructor.</remarks>
-  public static Tool CreateFromClass<T>() where T : ITool, new()
+  public static Tool CreateFromClass<T>(CacheControl? cacheControl = null) where T : ITool, new()
   {
     var tool = new T();
 
@@ -107,7 +113,7 @@ public class Tool
     ArgumentValidator.ThrowIfNullOrWhitespace(tool.Description, nameof(tool.Description));
     ArgumentValidator.ThrowIfNull(tool.Function, nameof(tool.Function));
 
-    return new Tool(tool.Name, tool.Description, new AnthropicFunction(tool.Function, tool));
+    return new Tool(tool.Name, tool.Description, new AnthropicFunction(tool.Function, tool), cacheControl);
   }
 
   /// <summary>
@@ -117,12 +123,19 @@ public class Tool
   /// <param name="description">The description of the tool.</param>
   /// <param name="type">The type that contains the method.</param>
   /// <param name="methodName">The name of the method.</param>
+  /// <param name="cacheControl">The cache control to be used for the tool.</param>
   /// <exception cref="ArgumentException">Thrown when <paramref name="methodName"/> is null or empty.</exception>
   /// <exception cref="ArgumentNullException">Thrown when <paramref name="type"/> is null.</exception>
   /// <exception cref="ArgumentException">Thrown when the method is not found in the type.</exception>
   /// <returns>The created tool as instance of <see cref="Tool"/>.</returns>
   /// <remarks>The name of the tool will be sanitized to conform to the Anthropic tool naming rules.</remarks>
-  public static Tool CreateFromStaticMethod(string name, string description, Type type, string methodName)
+  public static Tool CreateFromStaticMethod(
+    string name, 
+    string description, 
+    Type type, 
+    string methodName,
+    CacheControl? cacheControl = null
+  )
   {
     ArgumentValidator.ThrowIfNullOrWhitespace(methodName, nameof(methodName));
     ArgumentValidator.ThrowIfNull(type, nameof(type));
@@ -134,7 +147,7 @@ public class Tool
       throw new ArgumentException($"Method '{methodName}' not found in type '{type.FullName}'.", nameof(methodName));
     }
 
-    return new Tool(name, description, new AnthropicFunction(method));
+    return new Tool(name, description, new AnthropicFunction(method), cacheControl);
   }
 
   /// <summary>
@@ -144,12 +157,19 @@ public class Tool
   /// <param name="description">The description of the tool.</param>
   /// <param name="instance">The instance that contains the method.</param>
   /// <param name="methodName">The name of the method.</param>
+  /// <param name="cacheControl">The cache control to be used for the tool.</param>
   /// <exception cref="ArgumentException">Thrown when <paramref name="methodName"/> is null or empty.</exception> 
   /// <exception cref="ArgumentNullException">Thrown when <paramref name="instance"/> is null.</exception> 
   /// <exception cref="ArgumentException">Thrown when <paramref name="methodName"/> is not found in the type of <paramref name="instance"/>.</exception> 
   /// <returns>The created tool as instance of <see cref="Tool"/>.</returns>
   /// <remarks>The name of the tool will be sanitized to conform to the Anthropic tool naming rules.</remarks>
-  public static Tool CreateFromInstanceMethod(string name, string description, object instance, string methodName)
+  public static Tool CreateFromInstanceMethod(
+    string name, 
+    string description, 
+    object instance, 
+    string methodName,
+    CacheControl? cacheControl = null
+  )
   {
     ArgumentValidator.ThrowIfNullOrWhitespace(methodName, nameof(methodName));
     ArgumentValidator.ThrowIfNull(instance, nameof(instance));
@@ -161,7 +181,7 @@ public class Tool
       throw new ArgumentException($"Method '{methodName}' not found in type '{instance.GetType().FullName}'.", nameof(methodName));
     }
 
-    return new Tool(name, description, new AnthropicFunction(method, instance));
+    return new Tool(name, description, new AnthropicFunction(method, instance), null);
   }
 
   /// <summary>
@@ -171,14 +191,20 @@ public class Tool
   /// <param name="name">The name of the tool.</param>
   /// <param name="description">The description of the tool.</param>
   /// <param name="func">The function.</param>
+  /// <param name="cacheControl">The cache control to be used for the tool.</param>
   /// <exception cref="ArgumentNullException">Thrown when <paramref name="func"/> is null.</exception>
   /// <returns>The created tool as instance of <see cref="Tool"/>.</returns>
   /// <remarks>The name of the tool will be sanitized to conform to the Anthropic tool naming rules.</remarks>
-  public static Tool CreateFromFunction<TResult>(string name, string description, Func<TResult> func)
+  public static Tool CreateFromFunction<TResult>(
+    string name, 
+    string description, 
+    Func<TResult> func,
+    CacheControl? cacheControl = null
+  )
   {
     ArgumentValidator.ThrowIfNull(func, nameof(func));
 
-    return new Tool(name, description, new AnthropicFunction(func.Method, func.Target));
+    return new Tool(name, description, new AnthropicFunction(func.Method, func.Target), cacheControl);
   }
 
   /// <summary>
@@ -189,14 +215,20 @@ public class Tool
   /// <param name="name">The name of the tool.</param>
   /// <param name="description">The description of the tool.</param>
   /// <param name="func">The function.</param>
+  /// <param name="cacheControl">The cache control to be used for the tool.</param>
   /// <exception cref="ArgumentNullException">Thrown when <paramref name="func"/> is null.</exception>
   /// <returns>The created tool as instance of <see cref="Tool"/>.</returns>
   /// <remarks>The name of the tool will be sanitized to conform to the Anthropic tool naming rules.</remarks>
-  public static Tool CreateFromFunction<T1, TResult>(string name, string description, Func<T1, TResult> func)
+  public static Tool CreateFromFunction<T1, TResult>(
+    string name, 
+    string description, 
+    Func<T1, TResult> func,
+    CacheControl? cacheControl = null
+  )
   {
     ArgumentValidator.ThrowIfNull(func, nameof(func));
 
-    return new Tool(name, description, new AnthropicFunction(func.Method, func.Target));
+    return new Tool(name, description, new AnthropicFunction(func.Method, func.Target), cacheControl);
   }
 
   /// <summary>
@@ -208,14 +240,20 @@ public class Tool
   /// <param name="name">The name of the tool.</param>
   /// <param name="description">The description of the tool.</param>
   /// <param name="func">The function.</param>
+  /// <param name="cacheControl">The cache control to be used for the tool.</param>
   /// <exception cref="ArgumentNullException">Thrown when <paramref name="func"/> is null.</exception>
   /// <returns>The created tool as instance of <see cref="Tool"/>.</returns>
   /// <remarks>The name of the tool will be sanitized to conform to the Anthropic tool naming rules.</remarks>
-  public static Tool CreateFromFunction<T1, T2, TResult>(string name, string description, Func<T1, T2, TResult> func)
+  public static Tool CreateFromFunction<T1, T2, TResult>(
+    string name, 
+    string description, 
+    Func<T1, T2, TResult> func,
+    CacheControl? cacheControl = null
+  )
   {
     ArgumentValidator.ThrowIfNull(func, nameof(func));
 
-    return new Tool(name, description, new AnthropicFunction(func.Method, func.Target));
+    return new Tool(name, description, new AnthropicFunction(func.Method, func.Target), cacheControl);
   }
 
 

src/AnthropicClient/Models/Usage.cs

@@ -18,4 +18,16 @@ public class Usage
   /// </summary>
   [JsonPropertyName("output_tokens")]
   public int OutputTokens { get; init; }
+
+  /// <summary>
+  /// Gets the number of tokens written to the cache when creating a new entry
+  /// </summary>
+  [JsonPropertyName("cache_creation_input_tokens")]
+  public int CacheCreationInputTokens { get; init; }
+
+  /// <summary>
+  /// Gets the number of tokens retrieved from the cache for the request.
+  /// </summary>
+  [JsonPropertyName("cache_read_input_tokens")]
+  public int CacheReadInputTokens { get; init; }
 }