Add bounded DOCX text tool to FileContext

Author: KSemenenko

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to ManagedCode.FileContext are documented here.
 
+## 1.0.9
+
+- Add a native bounded DOCX text tool with paragraph and character cursors for long documents.
+- Read DOCX through scoped storage and the pinned Open XML SDK; exclude binary DOCX packages from generic text reads and search.
+
 ## 1.0.8
 
 - Add bounded PDF text/page metadata, full-page PNG rendering, and embedded-image extraction through scoped file tools and public byte APIs.

Directory.Build.props

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

README.md

@@ -25,6 +25,7 @@ Your host supplies an `IStorage` backend and a model client. FileContext supplie
 | Multiple files | Issue independent tool calls in one turn, with optional concurrent execution |
 | Workspace isolation | Resolve logical paths under a configured storage prefix |
 | Observable results | Receive structured `found` / `not_found` metadata results that survive session restoration |
+| Office document reads | Read bounded DOCX paragraph windows and XLSX cell ranges through native tools |
 
 Product code depends only on `ManagedCode.Storage.Core`, so concrete storage providers stay in your application. The integration suite exercises the real filesystem provider; other backends use the same `IStorage` contract.
 
@@ -45,7 +46,7 @@ flowchart LR
 Requires **.NET 10**. Add FileContext and the storage provider your application uses:
 
 ```bash
-dotnet add package ManagedCode.FileContext --version 1.0.8
+dotnet add package ManagedCode.FileContext --version 1.0.9
 dotnet add package ManagedCode.Storage.FileSystem --version 10.0.7
 ```
 
@@ -134,6 +135,7 @@ Standard `file_access_*` tools come from Agent Framework's `FileAccessProvider`.
 | `file_context_pdf_page_image` | Render one complete PDF page as PNG `DataContent` | Yes |
 | `file_context_pdf_images_info` | Count embedded images on one PDF page | Yes |
 | `file_context_pdf_image` | Extract one embedded PDF image as PNG `DataContent` | Yes |
+| `file_context_docx_text` | Read DOCX paragraph windows with a continuation cursor | Yes |
 | `file_context_info` | Return file presence and metadata without reading content | Yes |
 | `file_context_markdown_graph_search` | Build and ranked-search a Markdown knowledge graph | Yes |
 | `file_context_markdown_graph_export` | Export a graph as Mermaid, DOT, Turtle, or JSON-LD | Yes |
@@ -187,6 +189,8 @@ Results include `StartLine`, `EndLine`, `HasMore`, and `TotalLines` when the end
 
 For an authenticated PDF already held as bytes, `FileContextPdfTextExtractor.Extract`, `FileContextPdfImages.RenderPagePng`, and `FileContextPdfImages.ExtractPageImagesPng` work without storing it. Storage reads enforce `MaximumPdfReadBytes` (25 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.
 
+`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.
+
 ## Explore Markdown as a graph
 
 Use [ManagedCode.MarkdownLd.Kb](https://github.com/managedcode/markdown-ld-kb) to connect and search concepts across the Markdown documents in your workspace:
@@ -359,7 +363,7 @@ dotnet pack src/ManagedCode.FileContext/ManagedCode.FileContext.csproj --configu
 
 ## Releases and license
 
-Version `1.0.8` is defined centrally in `Directory.Build.props`. Every push to `main` runs the Release workflow: restore, format, build, test with coverage, and pack. For a new package version, it publishes the validated NuGet artifact and creates the matching tag and GitHub release automatically. Already released versions are skipped. To release an update, bump the version, commit, and push; no manual tag is required.
+Version `1.0.9` is defined centrally in `Directory.Build.props`. Every push to `main` runs the Release workflow: restore, format, build, test with coverage, and pack. For a new package version, it publishes the validated NuGet artifact and creates the matching tag and GitHub release automatically. Already released versions are skipped. To release an update, bump the version, commit, and push; no manual tag is required.
 
 [MIT licensed](https://github.com/managedcode/FileContext/blob/main/LICENSE) · Built by [ManagedCode](https://github.com/managedcode)
 

docs/Architecture.md

@@ -106,6 +106,8 @@ flowchart LR
 `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.
+The same service opens DOCX packages read-only and streams bounded paragraph text through
+`FileContextDocxReader`, returning a cursor for later paragraph windows.
 
 ```mermaid
 flowchart LR

docs/Features/file-context.md

@@ -4,7 +4,7 @@
 
 ManagedCode.FileContext lets an Agent Framework agent work with files from any ManagedCode.Storage provider and query Markdown files as a knowledge graph.
 
-In scope: standard file access, bounded line navigation, metadata, Markdown graph retrieval/export, DI, path isolation, and deterministic tool-loop testing. Out of scope: provider credentials, direct model hosting, binary document parsing, and an alternative file protocol.
+In scope: standard file access, bounded line navigation, metadata, native PDF/DOCX/XLSX reads, Markdown graph retrieval/export, DI, path isolation, and deterministic tool-loop testing. Out of scope: provider credentials, direct model hosting, and an alternative file protocol.
 
 ## Rules
 
@@ -23,7 +23,7 @@ In scope: standard file access, bounded line navigation, metadata, Markdown grap
 13. The context provider injects capability instructions and tools, not arbitrary file content as system instructions.
 14. DI supports both the default `IStorage` and a named/keyed `IStorage` registration.
 15. Optional `OperationTimeout` applies to each public storage/context operation, combining with caller cancellation and preserving one deadline across internal steps. It defaults to null; regex matching has its separate `RegexTimeout`.
-16. The NuGet package has version `1.0.8`; publication occurs only from the GitHub Actions release workflow.
+16. The NuGet package has version `1.0.9`; publication occurs only from the GitHub Actions release workflow.
 
 ## Main flow
 
@@ -87,7 +87,7 @@ Independent writes and range reads on eight different files are tested concurren
 9. A real Agent Framework loop receives an LlmTck tool call, executes storage-backed `file_access_read`, proves the file content reaches the second model request, and returns the expected final answer.
 10. LlmTck tool loops exercise every read-only, mutation, and extended tool against the real filesystem provider.
 11. A sparse 1 GiB file supports bounded repeated range reads without proportional allocation; a giant unterminated line fails at the configured byte boundary.
-12. The packed `1.0.8` package installs and runs in a clean smoke project.
+12. The packed `1.0.9` package installs and runs in a clean smoke project.
 
 ## Definition of done
 
@@ -115,4 +115,10 @@ Verification: DocumentCreationTests and DocumentValidationTests reopen real form
 
 ## PDF reads and vision images
 
+DOCX reading uses the native `file_context_docx_text` tool. It reads ordinary paragraph and table
+text from the scoped `.docx` package in bounded windows. Each result includes the next paragraph
+and character offset when more text remains, so an agent can continue without loading a long
+document into one model call. The tool does not execute macros, fetch external links, or perform
+OCR on embedded images. Generic text reads refuse DOCX, and text search skips it.
+
 `file_context_pdf_text` reports a bounded text-layer prefix, total page count, and one-based pages with almost no text. It performs no OCR. `file_context_pdf_page_image` renders a complete page as PNG. `file_context_pdf_images_info` counts embedded image objects, and `file_context_pdf_image` returns one object as PNG. The direct `IFileContextPdf` methods and public byte-oriented PDF APIs support the same operations. Storage-scoped PDF reads enforce a byte cap; page rendering enforces pixel and image-byte caps. Image tools return `DataContent`; host chat pipelines must forward it as image content rather than stringify a function result.

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

@@ -0,0 +1,24 @@
+using DocumentFormat.OpenXml.Packaging;
+
+namespace ManagedCode.FileContext;
+
+public sealed partial class FileContextDocumentService
+{
+    public Task<FileContextDocxText> ReadDocxTextAsync(string path, int startParagraph = 1,
+        int startCharacter = 0, int paragraphCount = 20, CancellationToken cancellationToken = default)
+    {
+        RequireExtension(path, ".docx");
+        ArgumentOutOfRangeException.ThrowIfLessThan(startParagraph, 1);
+        ArgumentOutOfRangeException.ThrowIfNegative(startCharacter);
+        ArgumentOutOfRangeException.ThrowIfLessThan(paragraphCount, 1);
+        ArgumentOutOfRangeException.ThrowIfGreaterThan(paragraphCount,
+            FileContextDefaults.MaximumDocxParagraphsPerRead);
+
+        return ReadSourceAsync(path, (buffer, token) =>
+        {
+            using var document = WordprocessingDocument.Open(buffer, false);
+            return FileContextDocxReader.Read(document, path, startParagraph, startCharacter,
+                paragraphCount, token);
+        }, options.MaximumDocxReadBytes, cancellationToken);
+    }
+}

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

@@ -23,15 +23,16 @@ private Task<T> ReadWorkbookAsync<T>(string path, Func<SpreadsheetDocument, Canc
         {
             using var document = SpreadsheetDocument.Open(buffer, false);
             return read(document, token);
-        }, cancellationToken);
+        }, options.MaximumFullReadBytes, cancellationToken);
     }
 
-    private Task<T> ReadSourceAsync<T>(string path, Func<MemoryStream, CancellationToken, T> read, CancellationToken cancellationToken) =>
+    private Task<T> ReadSourceAsync<T>(string path, Func<MemoryStream, CancellationToken, T> read,
+        long maximumBytes, CancellationToken cancellationToken) =>
         FileContextOperation.RunAsync(options.OperationTimeout, async token =>
         {
             var metadata = await store.GetMetadataAsync(path, token).ConfigureAwait(false)
                 ?? throw new FileNotFoundException("The document was not found in this file context.", path);
-            if (metadata.Length > (ulong)options.MaximumFullReadBytes)
+            if (metadata.Length > (ulong)maximumBytes)
             { throw new IOException("Document exceeds the configured source read budget."); }
             var source = await store.OpenReadAsync(path, token).ConfigureAwait(false);
             await using var lifetime = source.ConfigureAwait(false);
@@ -40,7 +41,7 @@ private Task<T> ReadSourceAsync<T>(string path, Func<MemoryStream, CancellationT
             int count;
             while ((count = await source.ReadAsync(chunk, token).ConfigureAwait(false)) > 0)
             {
-                if (buffer.Length + count > options.MaximumFullReadBytes)
+                if (buffer.Length + count > maximumBytes)
                 { throw new IOException("Document exceeds the configured source read budget."); }
                 buffer.Write(chunk, 0, count);
             }

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

@@ -7,6 +7,7 @@ public Task<FileContextTablesInfo> GetTablesInfoAsync(string path, int? headerRo
     {
         FileContextTableReader.Validate(path, headerRow);
         return ReadSourceAsync(path,
-            (buffer, token) => FileContextTableReader.Read(buffer, path, headerRow, delimiter, options, token), cancellationToken);
+            (buffer, token) => FileContextTableReader.Read(buffer, path, headerRow, delimiter, options, token),
+            options.MaximumFullReadBytes, cancellationToken);
     }
 }

src/ManagedCode.FileContext/Documents/FileContextDocxParagraph.cs

@@ -0,0 +1,4 @@
+namespace ManagedCode.FileContext;
+
+/// <summary>One paragraph or a segment of a long paragraph; character offsets are zero-based.</summary>
+public sealed record FileContextDocxParagraph(int Number, int CharacterOffset, string Text);

src/ManagedCode.FileContext/Documents/FileContextDocxReader.cs

@@ -0,0 +1,56 @@
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Wordprocessing;
+
+namespace ManagedCode.FileContext;
+
+internal static class FileContextDocxReader
+{
+    public static FileContextDocxText Read(WordprocessingDocument document, string path,
+        int startParagraph, int startCharacter, int paragraphCount, CancellationToken cancellationToken)
+    {
+        var main = document.MainDocumentPart
+            ?? throw new InvalidDataException("The DOCX has no main document part.");
+        using var reader = OpenXmlReader.Create(main);
+        var paragraphs = new List<FileContextDocxParagraph>();
+        var number = 0;
+        var remaining = FileContextDefaults.MaximumDocxTextCharacters;
+        while (reader.Read())
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            if (!reader.IsStartElement || reader.ElementType != typeof(Paragraph))
+            {
+                continue;
+            }
+
+            number++;
+            if (number < startParagraph)
+            {
+                continue;
+            }
+            if (paragraphs.Count == paragraphCount || remaining == 0)
+            {
+                return new FileContextDocxText(path, paragraphs, number, 0);
+            }
+
+            var paragraph = reader.LoadCurrentElement() as Paragraph
+                ?? throw new InvalidDataException("A DOCX paragraph could not be read.");
+            var text = paragraph.InnerText;
+            var offset = number == startParagraph ? startCharacter : 0;
+            if (offset > text.Length)
+            {
+                throw new ArgumentOutOfRangeException(nameof(startCharacter),
+                    "The character offset is beyond this paragraph.");
+            }
+            var length = Math.Min(text.Length - offset, remaining);
+            paragraphs.Add(new FileContextDocxParagraph(number, offset, text.Substring(offset, length)));
+            remaining -= length;
+            if (offset + length < text.Length)
+            {
+                return new FileContextDocxText(path, paragraphs, number, offset + length);
+            }
+        }
+
+        return new FileContextDocxText(path, paragraphs, null, 0);
+    }
+}