Add native XLSX worksheet and cell range reads

Author: KSemenenko

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to ManagedCode.FileContext are documented here.
 
+## 1.0.3
+
+- Add read-only native XLSX worksheet metadata and sparse cell-range tools, with stored types, exact coordinates and cached formula results.
+- Preserve scoped storage, read approvals, cancellation and source/output budgets; verify native reads through the actual agent tool loop.
+
 ## 1.0.1
 
 - Add scoped creation of text, CSV, XLSX workbooks and Unicode PDF documents.

Directory.Build.props

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

README.md

@@ -385,3 +385,15 @@ Document generation uses DocumentFormat.OpenXml (MIT), PdfPig (Apache-2.0), and
 ### Reading large files
 
 Use `file_context_info` first: it returns the exact byte length, content type and modification time without loading file contents. Search for relevant text, then request the needed line ranges. The context provider supplies this guidance to the model on invocation. Full reads remain available when the task requires complete contents; exhaustive processing should advance through ranges without omitting data or rereading unchanged ranges. Byte length is not a token count.
+
+### Native Excel reads
+
+Read-only contexts also expose `file_context_workbook_info` and `file_context_workbook_range`.
+Use `context.Documents.GetWorkbookInfoAsync(path)` to discover worksheet names, then
+`context.Documents.ReadWorkbookRangeAsync(path, sheet, startRow, rowCount, startColumn, columnCount)`.
+Rows and columns are one-based. Range results are sparse: absent cell coordinates are blank.
+Values retain stored numeric precision and text leading zeros. Formula text and the saved cached
+result are returned without evaluation; cached results may be absent or stale. Excel display
+formatting is not applied. These tools use the same relative-path scope, read approval policy,
+cancellation and configured source/range byte budgets as other reads. XLSX files must be present
+in the scoped store; text extraction is not required for these native reads.

docs/Architecture.md

@@ -100,3 +100,18 @@ flowchart LR
   Documents --> Store[ManagedCodeStorageFileStore]
   Store --> Storage[IStorage]
 ```
+
+## Native workbook reads
+
+`FileContextDocumentService` opens XLSX packages read-only from the scoped storage adapter.
+`FileContextWorkbookReader` maps worksheets and cell rectangles into package-owned result records.
+It preserves coordinates and stored types without evaluating formulas or accessing external links.
+
+```mermaid
+flowchart LR
+  Provider[FileContextProvider] --> Tools[Workbook metadata and range tools]
+  Tools --> Documents[FileContextDocumentService]
+  Documents --> Store[Scoped storage adapter]
+  Documents --> Reader[Read-only Open XML reader]
+  Reader --> Result[Sparse cells with coordinates and cached values]
+```

src/ManagedCode.FileContext/Documents/FileContextDocumentService.Reading.cs

@@ -0,0 +1,45 @@
+using DocumentFormat.OpenXml.Packaging;
+
+namespace ManagedCode.FileContext;
+
+public sealed partial class FileContextDocumentService
+{
+    public Task<FileContextWorkbookInfo> GetWorkbookInfoAsync(string path, CancellationToken cancellationToken = default) =>
+        ReadWorkbookAsync(path, (document, _) => FileContextWorkbookReader.Inspect(document, path), cancellationToken);
+
+    public Task<FileContextWorkbookRange> ReadWorkbookRangeAsync(string path, string sheet, int startRow, int rowCount,
+        int startColumn, int columnCount, CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(sheet);
+        FileContextWorkbookReader.ValidateRange(startRow, rowCount, startColumn, columnCount);
+        return ReadWorkbookAsync(path, (document, token) => FileContextWorkbookReader.Read(document, path, sheet,
+            startRow, rowCount, startColumn, columnCount, options.MaximumRangeReadBytes, token), cancellationToken);
+    }
+
+    private Task<T> ReadWorkbookAsync<T>(string path, Func<SpreadsheetDocument, CancellationToken, T> read, CancellationToken cancellationToken)
+    {
+        RequireExtension(path, ".xlsx");
+        return FileContextOperation.RunAsync(options.OperationTimeout, async token =>
+        {
+            var metadata = await store.GetMetadataAsync(path, token).ConfigureAwait(false)
+                ?? throw new FileNotFoundException("The workbook was not found in this file context.", path);
+            if (metadata.Length > (ulong)options.MaximumFullReadBytes)
+            { throw new IOException("Workbook exceeds the configured source read budget."); }
+            var source = await store.OpenReadAsync(path, token).ConfigureAwait(false);
+            await using var lifetime = source.ConfigureAwait(false);
+            using var buffer = new MemoryStream();
+            var chunk = new byte[81920];
+            int count;
+            while ((count = await source.ReadAsync(chunk, token).ConfigureAwait(false)) > 0)
+            {
+                if (buffer.Length + count > options.MaximumFullReadBytes)
+                { throw new IOException("Workbook exceeds the configured source read budget."); }
+                buffer.Write(chunk, 0, count);
+            }
+            buffer.Position = 0;
+            token.ThrowIfCancellationRequested();
+            using var document = SpreadsheetDocument.Open(buffer, false);
+            return read(document, token);
+        }, cancellationToken);
+    }
+}

src/ManagedCode.FileContext/Documents/FileContextDocumentService.cs

@@ -3,7 +3,7 @@
 namespace ManagedCode.FileContext;
 
 /// <summary>Creates new documents in the same scoped file store used by navigation and reads.</summary>
-public sealed class FileContextDocumentService(ManagedCodeStorageFileStore store, FileContextOptions options)
+public sealed partial class FileContextDocumentService(ManagedCodeStorageFileStore store, FileContextOptions options)
 {
     public Task<FileContextCreatedFile> CreateTextAsync(string fileName, string text, CancellationToken cancellationToken = default)
     {

src/ManagedCode.FileContext/Documents/FileContextWorkbookCell.cs

@@ -0,0 +1,4 @@
+namespace ManagedCode.FileContext;
+
+/// <summary>Formula is source text only. Value is the saved cached result and can be empty; formulas are never evaluated.</summary>
+public sealed record FileContextWorkbookCell(string Address, string Type, string Value, string? Formula);

src/ManagedCode.FileContext/Documents/FileContextWorkbookInfo.cs

@@ -0,0 +1,3 @@
+namespace ManagedCode.FileContext;
+
+public sealed record FileContextWorkbookInfo(string Path, IReadOnlyList<FileContextWorksheetInfo> Sheets);

src/ManagedCode.FileContext/Documents/FileContextWorkbookRange.cs

@@ -0,0 +1,4 @@
+namespace ManagedCode.FileContext;
+
+/// <summary>A sparse rectangular range. Coordinates absent from Cells are blank; values are stored values, not formatted display text.</summary>
+public sealed record FileContextWorkbookRange(string Path, string Sheet, string Range, IReadOnlyList<FileContextWorkbookCell> Cells);

src/ManagedCode.FileContext/Documents/FileContextWorkbookReader.cs

@@ -0,0 +1,122 @@
+using System.Globalization;
+using System.Text;
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Spreadsheet;
+
+namespace ManagedCode.FileContext;
+
+internal static class FileContextWorkbookReader
+{
+    private const int AlphabetLength = 26;
+    private const int MaximumRows = 1_048_576;
+    private const int MaximumColumns = 16_384;
+
+    public static FileContextWorkbookInfo Inspect(SpreadsheetDocument document, string path)
+    {
+        var workbook = RequireWorkbook(document);
+        var sheets = workbook.Workbook?.Sheets?.Elements<Sheet>() ?? [];
+        return new(path, sheets.Select(sheet => new FileContextWorksheetInfo(
+            sheet.Name?.Value ?? string.Empty,
+            sheet.State?.InnerText ?? "visible",
+            ((WorksheetPart)workbook.GetPartById(sheet.Id!)).Worksheet?.GetFirstChild<SheetDimension>()?.Reference?.Value)).ToArray());
+    }
+
+    public static FileContextWorkbookRange Read(SpreadsheetDocument document, string path, string sheetName,
+        int startRow, int rowCount, int startColumn, int columnCount, long byteLimit, CancellationToken token)
+    {
+        ValidateRange(startRow, rowCount, startColumn, columnCount);
+        var workbook = RequireWorkbook(document);
+        var sheet = workbook.Workbook?.Sheets?.Elements<Sheet>().SingleOrDefault(item =>
+            string.Equals(item.Name?.Value, sheetName, StringComparison.Ordinal))
+            ?? throw new ArgumentException("The requested worksheet does not exist.", nameof(sheetName));
+        var worksheet = workbook.GetPartById(sheet.Id!) as WorksheetPart
+            ?? throw new InvalidDataException("The requested sheet is not a worksheet.");
+        var strings = workbook.SharedStringTablePart?.SharedStringTable?.Elements<SharedStringItem>()
+            .Select(static item => string.Concat(item.Descendants<Text>().Select(text => text.Text))).ToArray() ?? [];
+        var cells = ReadCells(worksheet, strings, startRow, rowCount, startColumn, columnCount, byteLimit, token);
+        var range = $"{ColumnName(startColumn)}{startRow}:{ColumnName(startColumn + columnCount - 1)}{startRow + rowCount - 1}";
+        return new(path, sheetName, range, cells);
+    }
+
+    public static void ValidateRange(int startRow, int rowCount, int startColumn, int columnCount)
+    {
+        if (startRow < 1 || rowCount < 1 || (long)startRow + rowCount - 1 > MaximumRows)
+        { throw new ArgumentOutOfRangeException(nameof(rowCount), "The range must fit Excel's 1048576 rows, starting at one."); }
+        if (startColumn < 1 || columnCount < 1 || (long)startColumn + columnCount - 1 > MaximumColumns)
+        { throw new ArgumentOutOfRangeException(nameof(columnCount), "The range must fit Excel's 16384 columns, starting at one."); }
+    }
+
+    private static List<FileContextWorkbookCell> ReadCells(WorksheetPart worksheet, string[] strings,
+        int startRow, int rowCount, int startColumn, int columnCount, long byteLimit, CancellationToken token)
+    {
+        using var reader = OpenXmlReader.Create(worksheet);
+        var cells = new List<FileContextWorkbookCell>();
+        long bytes = 0;
+        var rowNumber = 0;
+        while (reader.Read())
+        {
+            token.ThrowIfCancellationRequested();
+            if (reader.ElementType != typeof(Row) || !reader.IsStartElement) { continue; }
+            var row = (Row)reader.LoadCurrentElement()!;
+            rowNumber = row.RowIndex is null ? rowNumber + 1 : checked((int)row.RowIndex.Value);
+            if (rowNumber < startRow || rowNumber >= startRow + rowCount) { continue; }
+            var column = 0;
+            foreach (var cell in row.Elements<Cell>())
+            {
+                token.ThrowIfCancellationRequested();
+                column = cell.CellReference is null ? column + 1 : ReadColumn(cell.CellReference.Value!);
+                if (column < startColumn || column >= startColumn + columnCount) { continue; }
+                var value = ReadCell(cell, strings, $"{ColumnName(column)}{rowNumber}");
+                bytes += Encoding.UTF8.GetByteCount(value.Value) + Encoding.UTF8.GetByteCount(value.Formula ?? string.Empty) + value.Address.Length + value.Type.Length;
+                if (bytes > byteLimit) { throw new IOException("Workbook range exceeds the configured read budget. Request a smaller range."); }
+                cells.Add(value);
+            }
+        }
+        return cells;
+    }
+
+    private static FileContextWorkbookCell ReadCell(Cell cell, string[] strings, string address)
+    {
+        var type = cell.DataType?.Value;
+        var value = cell.CellValue?.Text ?? string.Empty;
+        if (type == CellValues.SharedString)
+        {
+            if (!int.TryParse(value, NumberStyles.None, CultureInfo.InvariantCulture, out var index) || index < 0 || index >= strings.Length)
+            { throw new InvalidDataException("Workbook cell contains an invalid shared-string reference."); }
+            value = strings[index];
+        }
+        if (type == CellValues.InlineString)
+        { value = string.Concat(cell.InlineString?.Descendants<Text>().Select(static text => text.Text) ?? []); }
+        var kind = "number";
+        if (type == CellValues.SharedString || type == CellValues.InlineString || type == CellValues.String) { kind = "text"; }
+        else if (type == CellValues.Boolean) { kind = "boolean"; }
+        else if (type == CellValues.Error) { kind = "error"; }
+        else if (type == CellValues.Date) { kind = "date"; }
+        else if (value.Length == 0) { kind = "blank"; }
+        return new(address, kind, value, cell.CellFormula?.Text);
+    }
+
+    private static WorkbookPart RequireWorkbook(SpreadsheetDocument document) =>
+        document.WorkbookPart ?? throw new InvalidDataException("The package has no Excel workbook.");
+
+    private static int ReadColumn(string address)
+    {
+        var result = 0;
+        foreach (var character in address.TakeWhile(char.IsAsciiLetter))
+        { result = checked(result * AlphabetLength + char.ToUpperInvariant(character) - 'A' + 1); }
+        return result;
+    }
+
+    private static string ColumnName(int column)
+    {
+        var result = new StringBuilder();
+        while (column > 0)
+        {
+            column--;
+            result.Insert(0, (char)('A' + column % AlphabetLength));
+            column /= AlphabetLength;
+        }
+        return result.ToString();
+    }
+}