Skip to content

Architecture.md

Latest commit

 

History

History
126 lines (102 loc) · 6.95 KB

Architecture.md

File metadata and controls

126 lines (102 loc) · 6.95 KB
Raw

Architecture

ManagedCode.FileContext is a narrow adapter between ManagedCode.Storage and Microsoft Agent Framework. It keeps storage-provider choice outside the package while adding agent-ready file and Markdown graph context.

System map

flowchart LR
  Agent["Microsoft Agent Framework agent"]
  Provider["FileContextProvider"]
  BuiltIn["FileAccessProvider"]
  Extended["FileContext tools"]
  Adapter["ManagedCodeStorageFileStore"]
  Service["FileContextService"]
  Storage(("IStorage"))
  Markdown["ManagedCode.MarkdownLd.Kb"]

  Agent --> Provider
  Provider --> BuiltIn
  Provider --> Extended
  BuiltIn --> Adapter
  Extended --> Service
  Service --> Adapter
  Adapter --> Storage
  Service --> Storage
  Service --> Markdown
Loading

Invocation flow

sequenceDiagram
  participant Caller
  participant Agent
  participant Provider as FileContextProvider
  participant Tool as File tool
  participant Store as ManagedCodeStorageFileStore
  participant Storage as IStorage

  Caller->>Agent: Run with user request
  Agent->>Provider: InvokingAsync
  Provider-->>Agent: instructions plus standard and extended tools
  Agent->>Tool: selected tool call
  Tool->>Store: normalized relative path
  Store->>Storage: stream or metadata operation
  Storage-->>Store: provider-neutral result
  Store-->>Tool: bounded result
  Tool-->>Agent: observable content or metadata
  Agent-->>Caller: final response
Loading

Modules and contracts

  • ManagedCodeStorageFileStore implements Microsoft AgentFileStore over IStorage. It owns path normalization, prefix isolation, direct-child projection, bounded full reads, and regex scanning.
  • FileContextProvider composes the Microsoft FileAccessProvider with package-owned read-range, metadata, and Markdown graph tools.
  • IFileContext is the direct application API for bounded range reads, metadata, graph search, and graph export.
  • FileContextService streams line windows and metadata, loads scoped Markdown through IStorage, builds a Markdown-LD knowledge graph, and maps results to package-owned records.
  • FileContextServiceCollectionExtensions is the composition root for default and keyed IStorage registrations.

Dependency rules

flowchart TD
  Product["ManagedCode.FileContext"] --> StorageCore["ManagedCode.Storage.Core"]
  Product --> AgentFramework["Microsoft.Agents.AI"]
  Product --> MarkdownLd["ManagedCode.MarkdownLd.Kb"]
  Product --> Extensions["Microsoft.Extensions.*"]
  Tests["ManagedCode.FileContext.Tests"] --> Product
  Tests --> FileSystem["ManagedCode.Storage.FileSystem"]
  Tests --> LlmTck["ManagedCode.LlmTck"]
Loading
  • Product code may depend on ManagedCode.Storage.Core but never a concrete provider. PDF inspection uses PdfPig; page rasterization uses the Apache-2.0 PdfPig Skia renderer and returns bounded PNG content to the host.
  • Tests own concrete filesystem storage, LlmTck hosting, and OpenAI-compatible protocol dependencies.
  • Microsoft owns the standard file-access tool names and behavior. This package adapts storage and adds only complementary tools.
  • File contents remain untrusted data and are never elevated to system instructions.

Operational limits

PDF callers share FileContextPdfProcessor, acquiring a permit before reading or downloading the source and retaining it through parsing/rendering. MaximumConcurrentPdfOperations defaults to one. FileContextPdfRenderDocument exposes page count and sequential page rendering from one parsed PDF; dispose it after the batch. The low-level synchronous image helpers remain caller-scheduled APIs.

PDF text, page rendering and embedded-image APIs accept bounded seekable streams. Storage-backed PDF tools retain seekable local FileStream/MemoryStream inputs but asynchronously stage other streams, including seekable cloud streams, to an automatically deleted temporary file. PdfPig's synchronous byte reads and seeks then remain local, without blocking on repeated network ranges. PdfSourceStagingMode.TemporaryFile also stages local inputs. PdfSourceBufferBytes bounds every copy read and PdfTemporaryDirectory optionally selects an existing host directory. No whole-document managed array is created. Native raster decoding has a separate per-page source-image pixel budget; lowering output scale does not reduce source bitmap allocation.

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

Generated documents

FileContextDocumentService shares ManagedCodeStorageFileStore with standard navigation and bounded reads. It creates new UTF-8 text/CSV, XLSX workbooks, paginated PDF documents, and branded report PDF/HTML/chart PNG output under unique relative paths. Report rendering uses an embedded Noto Sans font and Skia, receives host-resolved image bytes, and never makes network requests. See branded reports. FileContextDocumentTools supplies the same native functions to FileContextProvider or a host-owned tool registry.

flowchart LR
  Provider[FileContextProvider] --> Tools[FileContextDocumentTools]
  Host[Host native and JavaScript tools] --> Tools
  Tools --> Documents[FileContextDocumentService]
  Documents --> Writers[CSV OpenXml PdfPig Skia report renderer]
  Documents --> Store[ManagedCodeStorageFileStore]
  Store --> Storage[IStorage]
Loading

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. The same service opens DOCX packages read-only and streams bounded paragraph text through FileContextDocxReader, returning a cursor for later paragraph windows.

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]
Loading