Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Directory.Build.targets
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
<NoWarn>$(NoWarn);AD0001</NoWarn>

<!-- Experimental warnings are for customers, not for this repo -->
<NoWarn>$(NoWarn);EXTEXP0001;EXTEXP0002;EXTEXP0003;EXTEXP0004;EXTEXP0005;EXTEXP0006;EXTEXP0007;EXTEXP0008;EXTEXP0009;EXTEXP0010;EXTEXP0011;EXTEXP0012;EXTEXP0013;EXTEXP0014;EXTEXP0015;EXTEXP0016;EXTEXP0017;EXTEXP0018;MEVD9001</NoWarn>
<NoWarn>$(NoWarn);EXTEXP0001;EXTEXP0002;EXTEXP0003;EXTEXP0004;EXTEXP0005;EXTEXP0006;EXTEXP0007;EXTEXP0008;EXTEXP0009;EXTEXP0010;EXTEXP0011;EXTEXP0012;EXTEXP0013;EXTEXP0014;EXTEXP0015;EXTEXP0016;EXTEXP0017;EXTEXP0018;EXTEXP0019;MEVD9001</NoWarn>

<!-- Obsoletion warnings are for customers, not for this repo -->
<NoWarn>$(NoWarn);EXTOBS0001;</NoWarn>
Expand Down
1 change: 1 addition & 0 deletions docs/list-of-diagnostics.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ if desired.
| `EXTEXP0016` | Hosting integration testing experiments |
| `EXTEXP0017` | Contextual options experiments |
| `EXTEXP0018` | HybridCache experiments |
| `EXTEXP0019` | Documents experiments |
| `MEAI001` | AI experiments |
| `MEVD9001` | Vector Data experiments |

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System;
using System.Collections.Generic;
using System.Text.Json.Serialization;
using Microsoft.Extensions.AI;
using Microsoft.Shared.Diagnostics;

namespace Microsoft.Extensions.Documents;

/// <summary>
/// Represents an ordered, provider-neutral structured document.
/// </summary>
public sealed class ExtractionDocument
{
/// <summary>
/// Initializes a new instance of the <see cref="ExtractionDocument"/> class.
/// </summary>
/// <param name="identifier">The local identifier of the document.</param>
/// <param name="content">The local payload, or <see langword="null"/> for a structural document.</param>
public ExtractionDocument(string identifier, AIContent? content = null)
{
Identifier = Throw.IfNullOrEmpty(identifier);
Content = content;
}

/// <summary>Gets the document identifier.</summary>
public string Identifier { get; }

/// <summary>Gets or sets the local payload of the document, excluding its sections.</summary>
/// <remarks>Payloads are borrowed and mutable; their interpretation is determined by the producer.</remarks>
public AIContent? Content { get; set; }

/// <summary>Gets the ordered root sections of the document.</summary>
public List<ExtractionDocumentSection> Sections { get; } = [];

/// <summary>Gets the metadata associated with the document.</summary>
public Dictionary<string, object?> Metadata { get; } = new(StringComparer.Ordinal);

/// <summary>Gets source frames, independently of assembled section order.</summary>
/// <remarks>Producers explicitly add frames, including blank frames with no content elements.</remarks>
public List<ExtractionDocumentSourcePage> SourcePages { get; } = [];

/// <summary>Gets or sets the optional borrowed native document result.</summary>
/// <remarks>
/// Native data is not implicitly disposed, deep-cloned, logged or serialized.
/// This does not guarantee original response bytes or durable serialization.
/// </remarks>
[JsonIgnore]
public object? RawRepresentation { get; set; }

/// <summary>Enumerates non-section content in depth-first document order.</summary>
/// <remarks>
/// This structural traversal does not flatten table cells or return document/section-local payloads.
/// Use the hierarchy to inspect those local payloads and table cells directly.
/// Cyclic section relationships and null entries are rejected when traversed.
/// </remarks>
/// <returns>The content elements in document order.</returns>
public IEnumerable<ExtractionDocumentElement> EnumerateContent()
{
HashSet<ExtractionDocumentSection> path = [];
foreach (ExtractionDocumentSection section in Sections)
{
foreach (ExtractionDocumentElement element in EnumerateSection(section, path))
{
yield return element;
}
}
}

private static IEnumerable<ExtractionDocumentElement> EnumerateSection(
ExtractionDocumentSection section, HashSet<ExtractionDocumentSection> path)
{
if (section is null || !path.Add(section))
{
throw new InvalidOperationException("A document cannot traverse a null section or a cyclic section relationship.");
}

try
{
foreach (ExtractionDocumentElement element in section.Elements)
{
if (element is null)
{
throw new InvalidOperationException("A document cannot traverse a null element.");
}

if (element is ExtractionDocumentSection nestedSection)
{
foreach (ExtractionDocumentElement nestedElement in EnumerateSection(nestedSection, path))
{
yield return nestedElement;
}
}
else
{
yield return element;
}
}
}
finally
{
_ = path.Remove(section);
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System;
using System.Collections.Generic;
using Microsoft.Extensions.AI;
using Microsoft.Shared.Diagnostics;

namespace Microsoft.Extensions.Documents;

/// <summary>Represents an element in a structured document.</summary>
public abstract class ExtractionDocumentElement
{
/// <summary>Initializes a new instance of the <see cref="ExtractionDocumentElement"/> class.</summary>
/// <param name="content">The local payload, or <see langword="null"/> for a structural element.</param>
protected ExtractionDocumentElement(AIContent? content) => Content = content;

/// <summary>Gets or sets the local payload of this element.</summary>
/// <remarks>
/// TextContent can contain plain text or producer-supplied formatted text. Structural elements can have no payload.
/// Content is local: do not store an aggregate copy of descendant content here.
/// Payloads and their metadata are borrowed and mutable.
/// Text elements require nonnull <see cref="TextContent"/>, including assignments through a base reference.
/// </remarks>
public AIContent? Content
{
get;
set
{
if (this is ExtractionDocumentTextElement)
{
_ = Throw.IfNull(value);
if (value is not TextContent)
{
Throw.ArgumentException(nameof(value), "A text element requires TextContent.");
}
}

field = value;
}
}

/// <summary>Gets optional page and region associations.</summary>
/// <remarks>Adding a reference does not add its page to a document. Producers explicitly populate the source-page list.</remarks>
public List<ExtractionDocumentSourceReference> Sources { get; } = [];
}

/// <summary>Represents a section in a document. Sections can be nested in the ordered element collection.</summary>
public sealed class ExtractionDocumentSection : ExtractionDocumentElement
{
/// <summary>Initializes a new instance of the <see cref="ExtractionDocumentSection"/> class.</summary>
/// <param name="content">The local payload, or <see langword="null"/> for a structural section.</param>
public ExtractionDocumentSection(AIContent? content = null)
: base(content)
{
}

/// <summary>Gets the ordered elements in this section, including nested sections.</summary>
public List<ExtractionDocumentElement> Elements { get; } = [];
}

/// <summary>Represents text in a document, with an optional semantic role.</summary>
public sealed class ExtractionDocumentTextElement : ExtractionDocumentElement
{
/// <summary>Initializes a new instance of the <see cref="ExtractionDocumentTextElement"/> class.</summary>
/// <param name="content">The text payload, without a required formatting convention.</param>
/// <param name="role">The optional semantic role, or <see langword="null"/> when unspecified.</param>
public ExtractionDocumentTextElement(TextContent content, string? role = null)
: base(Throw.IfNull(content))
{
Role = role is null ? null : Throw.IfNullOrWhitespace(role);
}

/// <summary>Gets the optional semantic role of this text element.</summary>
/// <remarks>
/// Common roles are <c>heading</c> for a document heading, <c>pageHeader</c> for repeated page headers,
/// and <c>pageFooter</c> for repeated page footers. Custom roles are preserved without normalization.
/// Consumers should treat unspecified or unrecognized roles as ordinary text.
/// </remarks>
public string? Role { get; }

/// <summary>Gets or sets the positive heading level, or <see langword="null"/> when unspecified.</summary>
/// <remarks>This property is meaningful for the <c>heading</c> role. An unspecified level does not imply a hierarchy level.</remarks>
public int? HeadingLevel
{
get;
set
{
if (value is not null)
{
_ = Throw.IfLessThanOrEqual(value.Value, 0, nameof(value));
}

field = value;
}
}
}

/// <summary>Represents an image in a document.</summary>
public sealed class ExtractionDocumentImageElement : ExtractionDocumentElement
{
/// <summary>Initializes a new instance of the <see cref="ExtractionDocumentImageElement"/> class.</summary>
/// <param name="content">The local image payload, such as image bytes, a reference, or producer-supplied text.</param>
/// <param name="text">The optional OCR or transcription text, independently of any caption or description.</param>
public ExtractionDocumentImageElement(AIContent? content = null, string? text = null)
: base(content)
{
Text = text;
}

/// <summary>Gets or sets the original asset reference, independently of any payload URI.</summary>
/// <remarks>No URI is fetched or fabricated by the model.</remarks>
public Uri? Source { get; set; }

/// <summary>Gets or sets OCR or transcription text associated with the image.</summary>
/// <remarks>Captions and descriptions belong in <see cref="AlternativeText"/> instead.</remarks>
public string? Text { get; set; }

/// <summary>Gets or sets the alternative text for the image.</summary>
public string? AlternativeText { get; set; }
}
Loading