Configure FileContext PDF and image content through options

Author: KSemenenko

AGENTS.md

@@ -39,6 +39,8 @@ Tests use xUnit over VSTest. NuGet versions are centrally managed in `Directory.
 
 ## Boundaries
 
+- Expose FileContext behavior and limits through typed options registered with the standard `IOptions<T>` pattern; hosts bind configuration and consumers use those resolved options rather than introducing fixed capacity constants.
+- Expose image content as binary bytes, base64, and URL references through typed package APIs so hosts can select the correct model-visible representation.
 - `ManagedCode.Storage.Core.IStorage` is the only storage contract the product package may require.
 - Do not depend on a concrete storage provider in product code.
 - Keep Microsoft Agent Framework adaptation separate from Markdown graph materialization.

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to ManagedCode.FileContext are documented here.
 
+## 1.0.11
+
+- Bind and validate FileContext limits through `IOptions<FileContextOptions>`, including keyed registrations and host configuration.
+- Apply configured PDF source, page, and image limits to direct rendering and storage-backed tools.
+- Add typed model image content helpers for PNG bytes, base64, and HTTPS URL references.
+
 ## 1.0.10
 
 - Raise the bounded PDF source read limit from 25 MiB to 100 MiB for scanned documents while retaining per-page pixel and PNG output limits.

Directory.Build.props

@@ -12,7 +12,7 @@
     <AnalysisMode>Recommended</AnalysisMode>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <NoWarn>$(NoWarn);CS1591;MAAI001</NoWarn>
-    <Version>1.0.10</Version>
+    <Version>1.0.11</Version>
     <PackageVersion>$(Version)</PackageVersion>
   </PropertyGroup>
 

Directory.Packages.props

@@ -30,8 +30,8 @@
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.12" />
     <PackageVersion Include="Microsoft.Extensions.FileSystemGlobbing" Version="10.0.12" />
     <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.10.1" />
-    <PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.11" />
-    <PackageVersion Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="10.0.11" />
+    <PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.12" />
+    <PackageVersion Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="10.0.12" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.10.1" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.401" />
     <PackageVersion Include="OpenAI" Version="2.14.0" />

README.md

@@ -187,7 +187,7 @@ Results include `StartLine`, `EndLine`, `HasMore`, and `TotalLines` when the end
 
 `IFileContextPdf.ReadPdfTextAsync(path)` returns bounded text, `PageCount`, and one-based `PagesWithoutText`. It does not perform OCR. A scanned page can instead be rendered with `RenderPdfPageAsync(path, pageNumber)`, which returns PNG `DataContent`. Use `CountPdfPageImagesAsync` and `ExtractPdfImageAsync` when the original embedded pictures are needed rather than the complete page. The four read-only `file_context_pdf_*` tools expose the same operations from scoped storage.
 
-For an authenticated PDF already held as bytes, `FileContextPdfTextExtractor.Extract`, `FileContextPdfImages.RenderPagePng`, and `FileContextPdfImages.ExtractPageImagesPng` work without storing it. PDF source reads are capped at 100 MiB by default; page rasterization caps pixels and PNG size. A host must pass image `DataContent` to its model as image content. A generic OpenAI Chat function result serializes it as text, so hosts must explicitly bridge image tool results into a multimodal model message.
+For an authenticated PDF already held as bytes, `FileContextPdfTextExtractor.Extract`, `FileContextPdfImages.RenderPagePng`, and `FileContextPdfImages.ExtractPageImagesPng` work without storing it. PDF source reads default to 100 MiB and accept `FileContextOptions` for a different limit; page rasterization also uses configured pixel and PNG limits. `FileContextImageContent` creates model-visible `DataContent` from PNG bytes or base64 and `UriContent` from an HTTPS URL. A URL reference is not fetched by FileContext, so the model provider must be able to access it. A host must pass image content to its model as image content. A generic OpenAI Chat function result serializes it as text, so hosts must explicitly bridge image tool results into a multimodal model message.
 
 `file_context_docx_text(path, startParagraph?, startCharacter?, paragraphCount?)` reads ordinary paragraph and table text from a scoped DOCX package. The result contains numbered paragraph segments and `nextParagraph`/`nextCharacter`; use that cursor to continue a long document. Reads are limited to 50 paragraphs and 20,000 characters per call, with a configurable 25 MiB source limit (`MaximumDocxReadBytes`). It does not OCR embedded images. DOCX and XLSX packages are excluded from generic text reads and grep.
 
@@ -245,6 +245,11 @@ Paths are logical, relative, and `/`-separated. `RootPrefix` scopes storage acce
 
 | Option | Default |
 | --- | ---: |
+| `MaximumPdfReadBytes` | 100 MiB |
+| `MaximumImageBytes` | 8 MiB |
+| `MaximumRenderedPagePixels` / `MaximumImagesPerPdfPage` | 4,000,000 / 20 |
+| `DefaultPdfPageScale` / `MinimumPdfPageScale` / `MaximumPdfPageScale` | 1.5 / 0.5 / 3 |
+| `PdfPngQuality` | 100 |
 | `MaximumFullReadBytes` | 1 MiB |
 | `MaximumRangeReadBytes` | 256 KiB |
 | `DefaultRangeLineCount` / `MaximumRangeLineCount` | 200 / 1,000 |
@@ -263,7 +268,7 @@ These settings are available through `FileContextOptions`; their named defaults
 
 ### Configure limits and timeouts
 
-Every option in the table is configurable through `FileContextOptions`, for both default and keyed registrations. Configure the options before building your service provider:
+Every option in the table is configurable through `IOptions<FileContextOptions>`, for both default and keyed registrations. Configure the options before building your service provider:
 
 ```csharp
 services.AddManagedCodeFileContext(storage, options =>
@@ -291,17 +296,27 @@ services.AddManagedCodeFileContext(storage, options =>
 In a host that uses Microsoft configuration binding, the same options can come from `appsettings.json`, environment variables, or another configuration source:
 
 ```csharp
-using Microsoft.Extensions.Configuration;
+services.AddFileContextOptions(configuration);
+services.AddManagedCodeFileContext(storage);
+```
 
-services.AddManagedCodeFileContext(storage, options =>
-    configuration.GetSection("FileContext").Bind(options));
+The package binds the `FileContext` section through the standard options pipeline. For example:
+
+```csharp
+var options = provider.GetRequiredService<IOptions<FileContextOptions>>().Value;
+var page = FileContextPdfImages.RenderPagePng(pdfBytes, pageNumber, options);
+var raw = FileContextImageContent.FromPngBytes(page, options);
+var base64 = FileContextImageContent.ToBase64Png(page, options);
+var fromBase64 = FileContextImageContent.FromBase64Png(base64, options);
+var remote = FileContextImageContent.FromPngUrl(new Uri("https://example.com/page.png"));
 ```
 
-The host supplies `configuration` and the `Microsoft.Extensions.Configuration.Binder` package. For example:
+The URL form is a reference only; FileContext does not download it. Use a URL only when the model provider can fetch that resource.
 
 ```json
 {
   "FileContext": {
+    "MaximumPdfReadBytes": 104857600,
     "MaximumFullReadBytes": 4194304,
     "MaximumRangeReadBytes": 524288,
     "DefaultRangeLineCount": 100,
@@ -325,7 +340,7 @@ The host supplies `configuration` and the `Microsoft.Extensions.Configuration.Bi
 
 Configured deadline expiry surfaces as `TimeoutException`, which the function-invocation loop can return as a tool error. Caller cancellation remains `OperationCanceledException`. Cancellation is cooperative: a provider that ignores the token or a synchronous regex/graph operation can finish later than the deadline; FileContext awaits the work and checks cancellation before returning a successful result. Regex matching retains its own `RegexTimeout`.
 
-Options are bound at registration time; changing the configuration later does not automatically reconfigure an existing provider. To set a per-call deadline or allow the caller to cancel earlier, pass a cancellation token:
+`IOptions<FileContextOptions>` resolves the configured values when the provider is created. Existing providers keep their resolved options. To set a per-call deadline or allow the caller to cancel earlier, pass a cancellation token:
 
 ```csharp
 using var deadline = new CancellationTokenSource(TimeSpan.FromSeconds(30));

docs/Architecture.md

@@ -77,7 +77,7 @@ flowchart TD
 
 ## Operational limits
 
-All potentially large operations are controlled by `FileContextOptions`: full-read bytes, range bytes, files scanned, bytes per searched file, matches per file, total search results, graph documents, graph source bytes, and exported graph characters. Non-seekable cloud streams are supported by sequential streaming.
+All potentially large operations are controlled by `IOptions<FileContextOptions>`: PDF source/page/image budgets, full-read bytes, range bytes, files scanned, bytes per searched file, matches per file, total search results, graph documents, graph source bytes, and exported graph characters. Non-seekable cloud streams are supported by sequential streaming.
 
 ## Start here
 

src/ManagedCode.FileContext/FileContextDefaults.cs

@@ -1,13 +1,19 @@
-using ManagedCode.FileContext.Pdf;
-
 namespace ManagedCode.FileContext;
 
 /// <summary>Default limits and selectors used by <see cref="FileContextOptions" />.</summary>
 public static class FileContextDefaults
 {
+    public const int MaximumPdfPngQuality = 100;
     public const long MaximumGeneratedFileBytes = 64L * 1024L * 1024L;
     public const int FirstLineNumber = 1;
-    public const int MaximumPdfReadBytes = FileContextPdfImages.MaximumPdfBytes;
+    public const int MaximumPdfReadBytes = 100 * 1024 * 1024;
+    public const int MaximumImageBytes = 8 * 1024 * 1024;
+    public const int MaximumRenderedPagePixels = 4_000_000;
+    public const int MaximumImagesPerPdfPage = 20;
+    public const double DefaultPdfPageScale = 1.5;
+    public const double MinimumPdfPageScale = 0.5;
+    public const double MaximumPdfPageScale = 3;
+    public const int PdfPngQuality = 100;
     public const int MaximumPdfTextCharacters = 50_000;
     public const int MaximumDocxReadBytes = 25 * 1024 * 1024;
     public const int MaximumDocxTextCharacters = 20_000;

src/ManagedCode.FileContext/FileContextOptions.cs

@@ -3,6 +3,8 @@ namespace ManagedCode.FileContext;
 /// <summary>Controls file access, approval, search, and graph limits for one context provider.</summary>
 public sealed class FileContextOptions
 {
+    public const string SectionName = "FileContext";
+
     private static readonly TimeSpan MaximumOperationTimeout = TimeSpan.FromMilliseconds(uint.MaxValue - 1L);
     private static readonly TimeSpan MaximumRegexTimeout = TimeSpan.FromMilliseconds(int.MaxValue - 1);
 
@@ -21,6 +23,23 @@ public sealed class FileContextOptions
 
     public int MaximumPdfReadBytes { get; set; } = FileContextDefaults.MaximumPdfReadBytes;
 
+    public int MaximumImageBytes { get; set; } = FileContextDefaults.MaximumImageBytes;
+
+    public int MaximumRenderedPagePixels { get; set; } = FileContextDefaults.MaximumRenderedPagePixels;
+
+    public int MaximumImagesPerPdfPage { get; set; } = FileContextDefaults.MaximumImagesPerPdfPage;
+
+    public double DefaultPdfPageScale { get; set; } = FileContextDefaults.DefaultPdfPageScale;
+
+    public double MinimumPdfPageScale { get; set; } = FileContextDefaults.MinimumPdfPageScale;
+
+    public double MaximumPdfPageScale { get; set; } = FileContextDefaults.MaximumPdfPageScale;
+
+    public int PdfPngQuality { get; set; } = FileContextDefaults.PdfPngQuality;
+
+    /// <summary>Creates an independent copy for a scoped provider while retaining configured limits.</summary>
+    public FileContextOptions Clone() => (FileContextOptions)MemberwiseClone();
+
     public int MaximumDocxReadBytes { get; set; } = FileContextDefaults.MaximumDocxReadBytes;
 
     public long MaximumFullReadBytes { get; set; } = FileContextDefaults.MaximumFullReadBytes;
@@ -56,6 +75,19 @@ internal void Validate()
     {
         ValidatePositive(MaximumGeneratedFileBytes, nameof(MaximumGeneratedFileBytes));
         ValidatePositive(MaximumPdfReadBytes, nameof(MaximumPdfReadBytes));
+        ValidatePositive(MaximumImageBytes, nameof(MaximumImageBytes));
+        ValidatePositive(MaximumRenderedPagePixels, nameof(MaximumRenderedPagePixels));
+        ValidatePositive(MaximumImagesPerPdfPage, nameof(MaximumImagesPerPdfPage));
+        if (!double.IsFinite(MinimumPdfPageScale) || MinimumPdfPageScale <= 0
+            || !double.IsFinite(DefaultPdfPageScale) || DefaultPdfPageScale < MinimumPdfPageScale
+            || !double.IsFinite(MaximumPdfPageScale) || MaximumPdfPageScale < DefaultPdfPageScale)
+        {
+            throw new InvalidOperationException("PDF page scales must be finite, positive, and ordered.");
+        }
+        if (PdfPngQuality is < 0 or > FileContextDefaults.MaximumPdfPngQuality)
+        {
+            throw new InvalidOperationException("PDF PNG quality must be between 0 and 100.");
+        }
         ValidatePositive(MaximumDocxReadBytes, nameof(MaximumDocxReadBytes));
         ValidatePositive(MaximumFullReadBytes, nameof(MaximumFullReadBytes));
         ValidatePositive(MaximumRangeReadBytes, nameof(MaximumRangeReadBytes));

src/ManagedCode.FileContext/FileContextOptionsValidator.cs

@@ -0,0 +1,19 @@
+using Microsoft.Extensions.Options;
+
+namespace ManagedCode.FileContext;
+
+internal sealed class FileContextOptionsValidator : IValidateOptions<FileContextOptions>
+{
+    public ValidateOptionsResult Validate(string? name, FileContextOptions options)
+    {
+        try
+        {
+            options.Validate();
+            return ValidateOptionsResult.Success;
+        }
+        catch (InvalidOperationException exception)
+        {
+            return ValidateOptionsResult.Fail(exception.Message);
+        }
+    }
+}

src/ManagedCode.FileContext/FileContextService.Pdf.cs

@@ -6,7 +6,6 @@ namespace ManagedCode.FileContext;
 public sealed partial class FileContextService
 {
     private const string PdfExtension = ".pdf";
-    private const string PngMediaType = "image/png";
     private const int CopyBufferSize = 81920;
 
     public Task<FileContextPdfText> ReadPdfTextAsync(string path,
@@ -24,14 +23,14 @@ public Task<FileContextPdfText> ReadPdfTextAsync(string path,
     public Task<DataContent> RenderPdfPageAsync(string path, int pageNumber,
         CancellationToken cancellationToken = default) =>
         FileContextOperation.RunAsync(_options.OperationTimeout, async token =>
-            new DataContent(FileContextPdfImages.RenderPagePng(
-                await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber), PngMediaType), cancellationToken);
+            FileContextImageContent.FromPngBytes(FileContextPdfImages.RenderPagePng(
+                await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber, _options), _options), cancellationToken);
 
     public Task<int> CountPdfPageImagesAsync(string path, int pageNumber,
         CancellationToken cancellationToken = default) =>
         FileContextOperation.RunAsync(_options.OperationTimeout, async token =>
             FileContextPdfImages.ExtractPageImagesPng(
-                await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber).Count, cancellationToken);
+                await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber, _options).Count, cancellationToken);
 
     public Task<DataContent> ExtractPdfImageAsync(string path, int pageNumber, int imageNumber,
         CancellationToken cancellationToken = default)
@@ -40,12 +39,12 @@ public Task<DataContent> ExtractPdfImageAsync(string path, int pageNumber, int i
         return FileContextOperation.RunAsync(_options.OperationTimeout, async token =>
         {
             var images = FileContextPdfImages.ExtractPageImagesPng(
-                await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber);
+                await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber, _options);
             if (imageNumber > images.Count)
             {
                 throw new InvalidOperationException("The embedded image number is outside this PDF page.");
             }
-            return new DataContent(images[imageNumber - 1].PngBytes, PngMediaType);
+            return FileContextImageContent.FromPngBytes(images[imageNumber - 1].PngBytes, _options);
         }, cancellationToken);
     }