Merge pull request #24 from StevanFreeborn/stevanfreeborn/feat/add-pdf-support

feat: add pdf support

README.md

@@ -847,3 +847,66 @@ foreach (var content in response.Value.Content)
   }
 }
 ```
+
+### PDF Support
+
+Anthropic has recently introduced a feature called [PDF Support](https://docs.anthropic.com/en/docs/build-with-claude/pdf-support) that allows Claude to support PDF input and understand both text and visual content within documents. . This feature is covered in depth in [Anthropic's API Documentation](https://docs.anthropic.com/en/docs/build-with-claude/pdf-support).
+
+> [!NOTE]
+> This feature is in beta and requires you to set an `anthropic-beta` header on your requests to use it.
+> The value of the header should be `pdfs-2024-09-25`.
+
+When using this library you can opt-in to PDF support by adding the required header to the `HttpClient` instance you provide to the `AnthropicApiClient` constructor.
+
+```csharp
+using AnthropicClient;
+
+var httpClient = new HttpClient();
+httpClient.DefaultRequestHeaders.Add("anthropic-beta", "pdfs-2024-09-25");
+
+var client = new AnthropicApiClient(apiKey, httpClient);
+```
+
+PDF support can be used to provide a PDF document as input to the model. This can be used to provide additional context to the model or to ask for additional information from the model. This library aims to make using PDF support convenient by allowing you to provide the PDF document you want Anthropic's models to consider for use when creating a message.
+
+#### PDF Document
+
+You can provide a PDF document by providing its base64 encoded content as a `DocumentContent` instance in the list of messages in the `MessageRequest` or `StreamMessageRequest` constructor.
+
+```csharp
+using AnthropicClient;
+using AnthropicClient.Models;
+
+var request = new MessageRequest(
+  model: AnthropicModels.Claude35Sonnet,
+  messages: [
+    new(MessageRole.User, [new TextContent("What is the title of this paper?")]),
+    new(MessageRole.User, [new DocumentContent("application/pdf", base64Data)])
+  ]
+);
+
+var httpClient = new HttpClient();
+httpClient.DefaultRequestHeaders.Add("anthropic-beta", "pdfs-2024-09-25");
+
+var client = new AnthropicApiClient(apiKey, httpClient);
+
+var response = await client.CreateMessageAsync(request);
+
+if (response.IsSuccess is false)
+{
+  Console.WriteLine("Failed to create message");
+  Console.WriteLine("Error Type: {0}", response.Error.Error.Type);
+  Console.WriteLine("Error Message: {0}", response.Error.Error.Message);
+  return;
+}
+
+foreach (var content in response.Value.Content)
+{
+  switch (content)
+  {
+    case TextContent textContent:
+      Console.WriteLine(textContent.Text);
+      break;
+  }
+}
+```

src/AnthropicClient/Json/ContentConverter.cs

@@ -16,6 +16,7 @@ class ContentConverter : JsonConverter<Content>
     {
       ContentType.Text => JsonSerializer.Deserialize<TextContent>(root.GetRawText(), options)!,
       ContentType.Image => JsonSerializer.Deserialize<ImageContent>(root.GetRawText(), options)!,
+      ContentType.Document => JsonSerializer.Deserialize<DocumentContent>(root.GetRawText(), options)!,
       ContentType.ToolUse => JsonSerializer.Deserialize<ToolUseContent>(root.GetRawText(), options)!,
       ContentType.ToolResult => JsonSerializer.Deserialize<ToolResultContent>(root.GetRawText(), options)!,
       _ => throw new JsonException($"Unknown content type: {type}")

src/AnthropicClient/Models/ContentType.cs

@@ -24,4 +24,9 @@ public static class ContentType
   /// Represents the tool result content type.
   /// </summary>
   public const string ToolResult = "tool_result";
+
+  /// <summary>
+  /// Represents the document content type.
+  /// </summary>
+  public const string Document = "document";
 }

src/AnthropicClient/Models/DocumentContent.cs

@@ -0,0 +1,56 @@
+using System.Text.Json.Serialization;
+
+using AnthropicClient.Utils;
+
+namespace AnthropicClient.Models;
+
+/// <summary>
+/// Represents content from a document that is part of a message.
+/// </summary>
+public class DocumentContent : Content
+{
+  /// <summary>
+  /// Gets the source of the document.
+  /// </summary>
+  public DocumentSource Source { get; init; } = new();
+
+  [JsonConstructor]
+  internal DocumentContent()
+  {
+  }
+
+  private void Validate(string mediaType, string data)
+  {
+    ArgumentValidator.ThrowIfNull(mediaType, nameof(mediaType));
+    ArgumentValidator.ThrowIfNull(data, nameof(data));
+  }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="DocumentContent"/> class.
+  /// </summary>
+  /// <param name="mediaType">The media type of the document.</param>
+  /// <param name="data">The data of the document.</param>
+  /// <exception cref="ArgumentNullException">Thrown when the media type or data is null.</exception>
+  /// <returns>A new instance of the <see cref="DocumentContent"/> class.</returns>
+  public DocumentContent(string mediaType, string data) : base(ContentType.Document)
+  {
+    Validate(mediaType, data);
+
+    Source = new(mediaType, data);
+  }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="DocumentContent"/> class.
+  /// </summary>
+  /// <param name="mediaType">The media type of the document.</param>
+  /// <param name="data">The data of the document.</param>
+  /// <param name="cacheControl">The cache control to be used for the content.</param>
+  /// <returns>A new instance of the <see cref="DocumentContent"/> class.</returns>
+  /// <exception cref="ArgumentNullException">Thrown when the media type, data, or cache control is null.</exception>
+  public DocumentContent(string mediaType, string data, CacheControl cacheControl) : base(ContentType.Document, cacheControl)
+  {
+    Validate(mediaType, data);
+
+    Source = new(mediaType, data);
+  }
+}

src/AnthropicClient/Models/DocumentSource.cs

@@ -0,0 +1,49 @@
+using System.Text.Json.Serialization;
+
+using AnthropicClient.Utils;
+
+namespace AnthropicClient.Models;
+
+/// <summary>
+/// Represents a document source.
+/// </summary>
+public class DocumentSource
+{
+  /// <summary>
+  /// Gets the media type of the document.
+  /// </summary>
+  [JsonPropertyName("media_type")]
+  public string MediaType { get; init; } = string.Empty;
+
+  /// <summary>
+  /// Gets the data of the document.
+  /// </summary>
+  public string Data { get; init; } = string.Empty;
+
+  /// <summary>
+  /// Gets the type of encoding of the document data.
+  /// </summary>
+  public string Type { get; init; } = "base64";
+
+  [JsonConstructor]
+  internal DocumentSource()
+  {
+  }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="DocumentSource"/> class.
+  /// </summary>
+  /// <param name="mediaType">The media type of the document.</param>
+  /// <param name="data">The data of the document.</param>
+  /// <exception cref="ArgumentException">Thrown when the media type is invalid.</exception>
+  /// <exception cref="ArgumentNullException">Thrown when the media type or data is null.</exception>
+  /// <returns>A new instance of the <see cref="DocumentSource"/> class.</returns>
+  public DocumentSource(string mediaType, string data)
+  {
+    ArgumentValidator.ThrowIfNull(mediaType, nameof(mediaType));
+    ArgumentValidator.ThrowIfNull(data, nameof(data));
+
+    MediaType = mediaType;
+    Data = data;
+  }
+}

tests/AnthropicClient.Tests/EndToEnd/AnthropicApiClientTests.cs

@@ -222,4 +222,81 @@ public class ClientTests(ConfigurationFixture configFixture) : EndToEndTest(conf
     resultTwo.Value.Content.Should().NotBeNullOrEmpty();
     resultTwo.Value.Usage.CacheReadInputTokens.Should().BeGreaterThan(0);
   }
+
+  [Fact]
+  public async Task CreateMessageAsync_WhenProvidedWithPDF_ItShouldReturnResponse()
+  {
+    var pdfPath = GetTestFilePath("addendum.pdf");
+    var bytes = await File.ReadAllBytesAsync(pdfPath);
+    var base64Data = Convert.ToBase64String(bytes);
+
+    var request = new MessageRequest(
+      model: AnthropicModels.Claude35Sonnet,
+      messages: [
+        new(MessageRole.User, [new TextContent("What is the title of this paper?")]),
+        new(MessageRole.User, [new DocumentContent("application/pdf", base64Data)])
+      ]
+    );
+
+    var httpClient = new HttpClient();
+    httpClient.DefaultRequestHeaders.Add("anthropic-beta", "pdfs-2024-09-25");
+    var client = CreateClient(httpClient);
+
+    var result = await client.CreateMessageAsync(request);
+
+    result.IsSuccess.Should().BeTrue();
+    result.Value.Should().BeOfType<MessageResponse>();
+    result.Value.Content.Should().NotBeNullOrEmpty();
+
+    var text = result.Value.Content.Aggregate("", (acc, content) =>
+    {
+      if (content is TextContent textContent)
+      {
+        acc += textContent.Text;
+      }
+
+      return acc;
+    });
+
+    text.Should().Contain("Model Card Addendum: Claude 3.5 Haiku and Upgraded Claude 3.5 Sonnet");
+  }
+
+  [Fact]
+  public async Task CreateMessageAsync_WhenProvidedWithPDFWithCacheControl_ItShouldUseCache()
+  {
+    var pdfPath = GetTestFilePath("addendum.pdf");
+    var bytes = await File.ReadAllBytesAsync(pdfPath);
+    var base64Data = Convert.ToBase64String(bytes);
+
+    var httpClient = new HttpClient();
+    httpClient.DefaultRequestHeaders.Add("anthropic-beta", "pdfs-2024-09-25, prompt-caching-2024-07-31");
+    var client = CreateClient(httpClient);
+
+    var request = new MessageRequest(
+      model: AnthropicModels.Claude35Sonnet,
+      messages: [
+        new(MessageRole.User, [
+          new DocumentContent("application/pdf", base64Data, new EphemeralCacheControl()),
+          new TextContent("What is the title of this paper?")
+        ]),
+      ]
+    );
+
+    var resultOne = await client.CreateMessageAsync(request);
+
+    resultOne.IsSuccess.Should().BeTrue();
+    resultOne.Value.Should().BeOfType<MessageResponse>();
+    resultOne.Value.Content.Should().NotBeNullOrEmpty();
+    resultOne.Value.Usage.Should().Match<Usage>(u => u.CacheCreationInputTokens > 0 || u.CacheReadInputTokens > 0);
+
+    request.Messages.Add(new(MessageRole.Assistant, resultOne.Value.Content));
+    request.Messages.Add(new(MessageRole.User, [new TextContent("What is the main theme of this paper?")]));
+
+    var resultTwo = await client.CreateMessageAsync(request);
+
+    resultTwo.IsSuccess.Should().BeTrue();
+    resultTwo.Value.Should().BeOfType<MessageResponse>();
+    resultTwo.Value.Content.Should().NotBeNullOrEmpty();
+    resultTwo.Value.Usage.CacheReadInputTokens.Should().BeGreaterThan(0);
+  }
 }

tests/AnthropicClient.Tests/Integration/AnthropicApiClientTests.cs

@@ -359,4 +359,63 @@ public class AnthropicApiClientTests : IntegrationTest
       )
     ));
   }
+
+  [Fact]
+  public async Task CreateMessageAsync_WhenCalledAndMessageCreatedWithDocumentContent_ItShouldReturnMessage()
+  {
+    _mockHttpMessageHandler
+      .WhenCreateMessageRequest()
+      .Respond(
+        HttpStatusCode.OK,
+        "application/json",
+        @"{
+            ""content"": [
+              {
+                ""text"": ""It is a PDF"",
+                ""type"": ""text""
+              }
+            ],
+            ""id"": ""msg_013Zva2CMHLNnXjNJJKqJ2EF"",
+            ""model"": ""claude-3-5-sonnet-20240620"",
+            ""role"": ""assistant"",
+            ""stop_reason"": ""end_turn"",
+            ""stop_sequence"": null,
+            ""type"": ""message"",
+            ""usage"": {
+              ""input_tokens"": 10,
+              ""output_tokens"": 25
+            }
+        }"
+      );
+
+    var request = new MessageRequest(
+      model: AnthropicModels.Claude35Sonnet,
+      messages: [
+        new(MessageRole.User, [new TextContent("What is this?")]),
+        new(MessageRole.User, [new DocumentContent("application/pdf", "data")])
+      ]
+    );
+
+    var result = await Client.CreateMessageAsync(request);
+
+    result.IsSuccess.Should().BeTrue();
+    result.Value.Should().BeOfType<MessageResponse>();
+
+    var message = result.Value;
+    message.Id.Should().Be("msg_013Zva2CMHLNnXjNJJKqJ2EF");
+    message.Model.Should().Be("claude-3-5-sonnet-20240620");
+    message.Role.Should().Be("assistant");
+    message.StopReason.Should().Be("end_turn");
+    message.StopSequence.Should().BeNull();
+    message.Type.Should().Be("message");
+    message.Usage.InputTokens.Should().Be(10);
+    message.Usage.OutputTokens.Should().Be(25);
+    message.Content.Should().HaveCount(1);
+    message.ToolCall.Should().BeNull();
+
+    var textContent = message.Content[0];
+    textContent.Should().BeOfType<TextContent>();
+    textContent.As<TextContent>().Text.Should().Be("It is a PDF");
+    textContent.As<TextContent>().Type.Should().Be("text");
+  }
 }

tests/AnthropicClient.Tests/Unit/Models/ContentTypeTests.cs

@@ -5,40 +5,30 @@ public class ContentTypeTests
   [Fact]
   public void Text_WhenCalled_ItShouldReturnText()
   {
-    var expected = "text";
+    ContentType.Text.Should().Be("text");
-
-    var actual = ContentType.Text;
-
-    actual.Should().Be(expected);
   }
 
   [Fact]
   public void Image_WhenCalled_ItShouldReturnImage()
   {
-    var expected = "image";
+    ContentType.Image.Should().Be("image");
-
-    var actual = ContentType.Image;
-
-    actual.Should().Be(expected);
   }
 
   [Fact]
   public void ToolUse_WhenCalled_ItShouldReturnToolUse()
   {
-    var expected = "tool_use";
+    ContentType.ToolUse.Should().Be("tool_use");
-
-    var actual = ContentType.ToolUse;
-
-    actual.Should().Be(expected);
   }
 
   [Fact]
   public void ToolResult_WhenCalled_ItShouldReturnToolResult()
   {
-    var expected = "tool_result";
+    ContentType.ToolResult.Should().Be("tool_result");
+  }
 
-    var actual = ContentType.ToolResult;
+  [Fact]
-
+  public void Document_WhenCalled_ItShouldReturnDocument()
-    actual.Should().Be(expected);
+  {
+    ContentType.Document.Should().Be("document");
   }
 }

tests/AnthropicClient.Tests/Unit/Models/DocumentContentTests.cs

@@ -0,0 +1,119 @@
+namespace AnthropicClient.Tests.Unit.Models;
+
+public class DocumentContentTests : SerializationTest
+{
+  private readonly string _testJson = @"{
+    ""source"": { 
+      ""media_type"": ""application/pdf"",
+      ""data"": ""data"",
+      ""type"": ""base64""
+    },
+    ""type"": ""document""
+  }";
+
+  private readonly string _testJsonWithCacheControl = @"{
+    ""source"": { 
+      ""media_type"": ""application/pdf"",
+      ""data"": ""data"",
+      ""type"": ""base64""
+    },
+    ""cache_control"": { ""type"": ""ephemeral"" },
+    ""type"": ""document""
+  }";
+
+  [Fact]
+  public void Constructor_WhenCalled_ItShouldInitializeSource()
+  {
+    var expectedMediaType = "application/pdf";
+    var expectedData = "data";
+
+    var result = new DocumentContent(expectedMediaType, expectedData);
+
+    result.Source.Should().BeEquivalentTo(new DocumentSource(expectedMediaType, expectedData));
+  }
+
+  [Fact]
+  public void Constructor_WhenCalledAndMediaTypeIsNull_ItShouldThrowArgumentNullException()
+  {
+    var expectedData = "data";
+
+    var action = () => new DocumentContent(null!, expectedData);
+
+    action.Should().Throw<ArgumentNullException>();
+  }
+
+  [Fact]
+  public void Constructor_WhenCalledAndDataIsNull_ItShouldThrowArgumentNullException()
+  {
+    var expectedMediaType = "application/pdf";
+
+    var action = () => new DocumentContent(expectedMediaType, null!);
+
+    action.Should().Throw<ArgumentNullException>();
+  }
+
+  [Fact]
+  public void Constructor_WhenCalledWithCacheControl_ItShouldInitializeSourceAndCacheControl()
+  {
+    var expectedMediaType = "application/pdf";
+    var expectedData = "data";
+    var cacheControl = new EphemeralCacheControl();
+
+    var result = new DocumentContent(expectedMediaType, expectedData, cacheControl);
+
+    result.Source.Should().BeEquivalentTo(new DocumentSource(expectedMediaType, expectedData));
+    result.CacheControl.Should().BeSameAs(cacheControl);
+  }
+
+  [Fact]
+  public void Constructor_WhenCalledWithCacheControlAndMediaTypeIsNull_ItShouldThrowArgumentNullException()
+  {
+    var expectedData = "data";
+    var cacheControl = new EphemeralCacheControl();
+
+    var action = () => new DocumentContent(null!, expectedData, cacheControl);
+
+    action.Should().Throw<ArgumentNullException>();
+  }
+
+  [Fact]
+  public void Constructor_WhenCalledWithCacheControlAndDataIsNull_ItShouldThrowArgumentNullException()
+  {
+    var expectedMediaType = "application/pdf";
+    var cacheControl = new EphemeralCacheControl();
+
+    var action = () => new DocumentContent(expectedMediaType, null!, cacheControl);
+
+    action.Should().Throw<ArgumentNullException>();
+  }
+
+  [Fact]
+  public void JsonSerialization_WhenSerialized_ItShouldHaveExpectedShape()
+  {
+    var content = new DocumentContent("application/pdf", "data");
+
+    var actual = Serialize(content);
+
+    JsonAssert.Equal(_testJson, actual);
+  }
+
+  [Fact]
+  public void JsonSerialization_WhenSerializedWithCacheControl_ItShouldHaveExpectedShape()
+  {
+    var content = new DocumentContent("application/pdf", "data", new EphemeralCacheControl());
+
+    var actual = Serialize(content);
+
+    JsonAssert.Equal(_testJsonWithCacheControl, actual);
+  }
+
+  [Fact]
+  public void JsonDeserialization_WhenDeserialized_ItShouldHaveExpectedShape()
+  {
+    var expected = new DocumentContent("application/pdf", "data");
+
+    var actual = Deserialize<DocumentContent>(_testJson);
+
+    actual.Should().BeEquivalentTo(expected);
+  }
+}

tests/AnthropicClient.Tests/Unit/Models/DocumentSourceTests.cs

@@ -0,0 +1,49 @@
+namespace AnthropicClient.Tests.Unit.Models;
+
+public class DocumentSourceTests
+{
+  [Fact]
+  public void Constructor_WhenCalledWithValidArguments_ItShouldSetProperties()
+  {
+    var mediaType = "application/pdf";
+    var data = "base64data";
+
+    var source = new DocumentSource(mediaType, data);
+
+    source.MediaType.Should().Be(mediaType);
+    source.Data.Should().Be(data);
+  }
+
+  [Fact]
+  public void Constructor_WhenCalledWithNullMediaType_ItShouldThrowArgumentNullException()
+  {
+    string? mediaType = null;
+    var data = "base64data";
+
+    var action = () => new DocumentSource(mediaType!, data);
+
+    action.Should().Throw<ArgumentNullException>();
+  }
+
+  [Fact]
+  public void Constructor_WhenCalledWithNullData_ItShouldThrowArgumentNullException()
+  {
+    var mediaType = "application/pdf";
+    string? data = null;
+
+    var action = () => new DocumentSource(mediaType, data!);
+
+    action.Should().Throw<ArgumentNullException>();
+  }
+
+  [Fact]
+  public void Constructor_WhenCalled_ItShouldHaveTypePropertySetToBase64()
+  {
+    var mediaType = "application/pdf";
+    var data = "base64data";
+
+    var source = new DocumentSource(mediaType, data);
+
+    source.Type.Should().Be("base64");
+  }
+}