cli: expose metadata summary

Author: KSemenenko

AGENTS.md

@@ -31,6 +31,7 @@ If I tell you to remember something, you do the same, update
 - Image placeholders must emit Markdown image links (`![alt](file.png)`) that reference persisted artifacts; only fall back to bold text when no file is available.
 - If AI image enrichment yields no insight, log and continue instead of throwing—treat empty payloads as a soft failure.
 - When executing tests, always include the `ManualConversionDebugTests` suite; treat its failures as blocking.
+- Always run the full test suite after making changes and share the results with the user.
 - Telemetry work: instrument both overall document processing time and per-page duration with real metrics alongside traces—include histogram/counter coverage so latency is observable at both levels.
 - For large converters, structure them as partial classes and split related files into a dedicated subfolder.
 - Markdown hygiene: strip non-breaking, zero-width, or other non-printable spaces; replace them with regular ASCII spaces so output never contains invisible characters like the long space before `Add`.

Directory.Packages.props

@@ -41,4 +41,4 @@
     <PackageVersion Include="xunit" Version="2.9.3" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.4" />
   </ItemGroup>
-</Project>
+</Project>

README.md

@@ -266,6 +266,30 @@ Console.WriteLine(result.Markdown.Length);
 - `DocumentConverterResult` exposes `Markdown`, `Title`, `Segments`, `Artifacts`, and `Metadata` for downstream processing.
 - Apply custom behaviour through `MarkItDownOptions` (segment settings, AI providers, middleware) when constructing the client.
 
+### Metadata Keys
+
+The `MetadataKeys` static class centralises every metadata field the converters emit so you never have to guess string names. Use these constants when inspecting `DocumentConverterResult.Metadata`, per-segment metadata, or artifact metadata:
+
+```csharp
+await using var client = new MarkItDownClient();
+var result = await client.ConvertAsync(path);
+
+if (result.Metadata.TryGetValue(MetadataKeys.DocumentTitle, out var title))
+{
+    Console.WriteLine($"Detected title: {title}");
+}
+
+foreach (var table in result.Artifacts.Tables)
+{
+    if (table.Metadata.TryGetValue(MetadataKeys.TableComment, out var comment))
+    {
+        Console.WriteLine(comment);
+    }
+}
+```
+
+Notable keys include `MetadataKeys.TableComment` (table span hints), `MetadataKeys.EmailAttachments` (EML attachment summary), `MetadataKeys.NotebookCellsCount` (Jupyter statistics), and `MetadataKeys.ArchiveEntry` (ZIP entry provenance). Refer to `src/MarkItDown/Utilities/MetadataKeys.cs` for the full catalog; new format handlers add their metadata there so downstream consumers can rely on stable identifiers.
+
 ### CLI
 
 Prefer a guided experience? Run the bundled CLI to batch files or URLs:
@@ -276,6 +300,18 @@ dotnet run --project src/MarkItDown.Cli -- path/to/input
 
 Use `dotnet publish` with your preferred runtime identifier if you need a self-contained binary.
 
+Each run now surfaces the document title plus quick stats (pages, images, tables, attachments) in the conversion summary. These numbers come straight from `MetadataKeys` so the CLI mirrors what you see when processing results programmatically.
+
+#### Cloud Provider Configuration Prompts
+
+Choose **Configure cloud providers** in the CLI to register AI integrations without writing code. The prompts map directly to the corresponding option objects:
+
+- **Azure** → `AzureIntelligenceOptions` (`DocumentIntelligence`, `Vision`, `Media`) and supports endpoints, API keys/tokens, and Video Indexer account metadata.
+- **Google** → `GoogleIntelligenceOptions` with credentials for Vertex AI or Speech services.
+- **AWS** → `AwsIntelligenceOptions` for Rekognition/Transcribe style integrations.
+
+You can leave a prompt blank to keep the current value, or enter `-` to clear it. The saved settings are applied to every subsequent conversion until you change them or use **Clear all**. Combine these prompts with the metadata counts above to validate that enrichment providers are wired up correctly.
+
 ## 🏗️ Architecture
 
 ### Core Components

src/MarkItDown.Cli/ConversionResult.cs

@@ -2,7 +2,18 @@
 
 namespace MarkItDown.Cli;
 
-internal sealed record ConversionResult(string Input, string? Output, bool Success, string? Error, int SegmentCount);
+internal sealed record ConversionResult(
+    string Input,
+    string? Output,
+    bool Success,
+    string? Error,
+    int SegmentCount,
+    string? Title,
+    int PageCount,
+    int ImageCount,
+    int TableCount,
+    int AttachmentCount,
+    string? AttachmentSummary);
 
 internal sealed class ConversionSummary
 {
@@ -16,6 +27,14 @@ public ConversionSummary(IReadOnlyList<ConversionResult> results)
     public int SuccessCount => Results.Count(r => r.Success);
 
     public int FailureCount => Results.Count - SuccessCount;
+
+    public int TotalPages => Results.Sum(r => r.PageCount);
+
+    public int TotalImages => Results.Sum(r => r.ImageCount);
+
+    public int TotalTables => Results.Sum(r => r.TableCount);
+
+    public int TotalAttachments => Results.Sum(r => r.AttachmentCount);
 }
 
 internal readonly record struct ConversionProgress(int Processed, int Total, string Current);

src/MarkItDown.Cli/ConversionService.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Globalization;
 using System.IO;
 using System.Linq;
 using System.Text;
@@ -30,13 +31,14 @@ public async Task<ConversionSummary> ConvertFilesAsync(IReadOnlyList<string>? fi
 
             try
             {
-                var conversion = await markItDown.ConvertAsync(file, cancellationToken).ConfigureAwait(false);
-                var outputPath = await WriteMarkdownAsync(conversion.Markdown, file, outputDirectory, cancellationToken).ConfigureAwait(false);
-                results.Add(new ConversionResult(file, outputPath, true, null, conversion.Segments.Count));
+                await using var conversion = await markItDown.ConvertAsync(file, cancellationToken).ConfigureAwait(false);
+                var markdown = conversion.Markdown;
+                var outputPath = await WriteMarkdownAsync(markdown, file, outputDirectory, cancellationToken).ConfigureAwait(false);
+                results.Add(CreateSuccessResult(conversion, file, outputPath));
             }
             catch (Exception ex)
             {
-                results.Add(new ConversionResult(file, null, false, ex.Message, 0));
+                results.Add(new ConversionResult(file, null, false, ex.Message, 0, null, 0, 0, 0, 0, null));
             }
 
             progress?.Report(new ConversionProgress(index + 1, files.Count, file));
@@ -54,9 +56,11 @@ public async Task<ConversionSummary> ConvertUrlAsync(string url, string outputDi
 
         Directory.CreateDirectory(outputDirectory);
         var markItDown = new MarkItDownClient(options);
-        var conversion = await markItDown.ConvertFromUrlAsync(url, cancellationToken: cancellationToken).ConfigureAwait(false);
-        var outputPath = await WriteMarkdownAsync(conversion.Markdown, DeriveFileNameFromUrl(url, conversion.Title), outputDirectory, cancellationToken).ConfigureAwait(false);
-        var result = new ConversionResult(url, outputPath, true, null, conversion.Segments.Count);
+        await using var conversion = await markItDown.ConvertFromUrlAsync(url, cancellationToken: cancellationToken).ConfigureAwait(false);
+        var markdown = conversion.Markdown;
+        var fileName = DeriveFileNameFromUrl(url, ResolveTitle(conversion));
+        var outputPath = await WriteMarkdownAsync(markdown, fileName, outputDirectory, cancellationToken).ConfigureAwait(false);
+        var result = CreateSuccessResult(conversion, url, outputPath);
         return new ConversionSummary(new[] { result });
     }
 
@@ -92,4 +96,58 @@ private static async Task<string> WriteMarkdownAsync(string? markdown, string in
         await File.WriteAllTextAsync(path, markdown ?? string.Empty, Encoding.UTF8, cancellationToken).ConfigureAwait(false);
         return path;
     }
+
+    private static ConversionResult CreateSuccessResult(DocumentConverterResult conversion, string input, string outputPath)
+    {
+        var metadata = conversion.Metadata ?? new Dictionary<string, string>();
+        var title = ResolveTitle(conversion);
+        var pageCount = ParseCount(metadata, MetadataKeys.DocumentPages);
+        var imageCount = conversion.Artifacts?.Images?.Count ?? 0;
+        var tableCount = conversion.Artifacts?.Tables?.Count ?? 0;
+        var attachmentCount = ParseCount(metadata, MetadataKeys.EmailAttachmentsCount);
+        var attachmentSummary = TryGetValue(metadata, MetadataKeys.EmailAttachments);
+
+        return new ConversionResult(
+            input,
+            outputPath,
+            true,
+            null,
+            conversion.Segments.Count,
+            title,
+            pageCount,
+            imageCount,
+            tableCount,
+            attachmentCount,
+            string.IsNullOrWhiteSpace(attachmentSummary) ? null : attachmentSummary);
+    }
+
+    private static string? ResolveTitle(DocumentConverterResult conversion)
+    {
+        if (!string.IsNullOrWhiteSpace(conversion.Title))
+        {
+            return conversion.Title;
+        }
+
+        if (conversion.Metadata.TryGetValue(MetadataKeys.DocumentTitle, out var title) && !string.IsNullOrWhiteSpace(title))
+        {
+            return title;
+        }
+
+        return null;
+    }
+
+    private static int ParseCount(IReadOnlyDictionary<string, string> metadata, string key)
+    {
+        if (metadata.TryGetValue(key, out var value) &&
+            int.TryParse(value, NumberStyles.Integer, CultureInfo.InvariantCulture, out var parsed) &&
+            parsed >= 0)
+        {
+            return parsed;
+        }
+
+        return 0;
+    }
+
+    private static string? TryGetValue(IReadOnlyDictionary<string, string> metadata, string key)
+        => metadata.TryGetValue(key, out var value) ? value : null;
 }

src/MarkItDown.Cli/InteractiveCli.cs

@@ -136,7 +136,6 @@ private async Task ConvertDirectoryAsync()
         var summary = await RunWithProgressAsync(progress => conversionService.ConvertFilesAsync(files, outputDir, options, progress), files.Count);
         RenderSummary(summary);
         PromptToOpenDirectory(outputDir, summary);
-        PromptToOpenDirectory(outputDir, summary);
     }
 
     private async Task ConvertUrlAsync()
@@ -378,6 +377,8 @@ private void RenderSummary(ConversionSummary summary)
     {
         var table = new Table().Border(TableBorder.Rounded).Title("Conversion Summary");
         table.AddColumn("Input");
+        table.AddColumn("Title");
+        table.AddColumn("Highlights");
         table.AddColumn("Output");
         table.AddColumn("Segments");
         table.AddColumn("Status");
@@ -387,6 +388,8 @@ private void RenderSummary(ConversionSummary summary)
             var status = result.Success ? "[green]Success[/]" : $"[red]{Markup.Escape(result.Error ?? "Failed")}[/]";
             table.AddRow(
                 Markup.Escape(result.Input),
+                string.IsNullOrWhiteSpace(result.Title) ? "-" : Markup.Escape(result.Title),
+                FormatHighlights(result),
                 result.Output is null ? "-" : Markup.Escape(result.Output),
                 result.SegmentCount.ToString(),
                 status);
@@ -396,6 +399,62 @@ private void RenderSummary(ConversionSummary summary)
         var total = summary.Results.Count;
         var successPercent = total == 0 ? 0 : (double)summary.SuccessCount / total * 100d;
         AnsiConsole.MarkupLine($"[green]Completed[/]: {summary.SuccessCount}/{total} succeeded ({successPercent:0.##}%), [red]{summary.FailureCount} failed[/].");
+
+        var totals = BuildTotalsSummary(summary);
+        if (!string.IsNullOrWhiteSpace(totals))
+        {
+            AnsiConsole.MarkupLine(totals);
+        }
+    }
+
+    private static string FormatHighlights(ConversionResult result)
+    {
+        var parts = new List<string>();
+        if (result.PageCount > 0)
+        {
+            parts.Add($"Pages: {result.PageCount}");
+        }
+        if (result.ImageCount > 0)
+        {
+            parts.Add($"Images: {result.ImageCount}");
+        }
+        if (result.TableCount > 0)
+        {
+            parts.Add($"Tables: {result.TableCount}");
+        }
+        if (result.AttachmentCount > 0)
+        {
+            parts.Add($"Attachments: {result.AttachmentCount}");
+        }
+
+        return parts.Count == 0
+            ? "-"
+            : Markup.Escape(string.Join(", ", parts));
+    }
+
+    private static string? BuildTotalsSummary(ConversionSummary summary)
+    {
+        var aggregate = new List<string>();
+        if (summary.TotalPages > 0)
+        {
+            aggregate.Add($"pages: {summary.TotalPages}");
+        }
+        if (summary.TotalImages > 0)
+        {
+            aggregate.Add($"images: {summary.TotalImages}");
+        }
+        if (summary.TotalTables > 0)
+        {
+            aggregate.Add($"tables: {summary.TotalTables}");
+        }
+        if (summary.TotalAttachments > 0)
+        {
+            aggregate.Add($"attachments: {summary.TotalAttachments}");
+        }
+
+        return aggregate.Count == 0
+            ? null
+            : $"[grey]Aggregate[/]: {string.Join(", ", aggregate)}.";
     }
 
     private void PreviewFile()

src/MarkItDown/Converters/Documents/EmlConverter.cs

@@ -97,7 +97,7 @@ public override async Task<DocumentConverterResult> ConvertAsync(Stream stream,
                 [MetadataKeys.DocumentPages] = extraction.Segments.Count.ToString(CultureInfo.InvariantCulture),
                 [MetadataKeys.DocumentImages] = extraction.Artifacts.Images.Count.ToString(CultureInfo.InvariantCulture),
                 [MetadataKeys.DocumentTables] = extraction.Artifacts.Tables.Count.ToString(CultureInfo.InvariantCulture),
-                ["email.attachments.count"] = conversion.Attachments.Count.ToString(CultureInfo.InvariantCulture),
+                [MetadataKeys.EmailAttachmentsCount] = conversion.Attachments.Count.ToString(CultureInfo.InvariantCulture),
                 [MetadataKeys.WorkspaceDirectory] = workspace.DirectoryPath
             };
 
@@ -108,7 +108,7 @@ public override async Task<DocumentConverterResult> ConvertAsync(Stream stream,
 
             if (conversion.Attachments.Count > 0)
             {
-                metadata["email.attachments"] = string.Join("; ", conversion.Attachments.Select(static attachment => attachment.Name));
+                metadata[MetadataKeys.EmailAttachments] = string.Join("; ", conversion.Attachments.Select(static attachment => attachment.Name));
             }
 
             foreach (var pair in extraction.Artifacts.Metadata)
@@ -357,8 +357,8 @@ private EmlExtractionResult BuildExtraction(string markdown, StreamInfo streamIn
 
         if (attachments.Count > 0)
         {
-            artifacts.Metadata["email.attachments.count"] = attachments.Count.ToString(CultureInfo.InvariantCulture);
-            artifacts.Metadata["email.attachments"] = string.Join("; ", attachments.Select(static attachment => attachment.Name));
+            artifacts.Metadata[MetadataKeys.EmailAttachmentsCount] = attachments.Count.ToString(CultureInfo.InvariantCulture);
+            artifacts.Metadata[MetadataKeys.EmailAttachments] = string.Join("; ", attachments.Select(static attachment => attachment.Name));
         }
 
         return new EmlExtractionResult(segments, artifacts);

src/MarkItDown/Converters/Documents/EpubConverter.cs

@@ -269,13 +269,13 @@ private static async Task<Dictionary<string, string>> ExtractMetadataAsync(ZipAr
         }
 
         var manager = BuildNamespaceManager(document);
-        metadata["title"] = GetFirstTextContent(document, "//opf:metadata/dc:title", manager);
-        metadata["author"] = string.Join(", ", GetAllTextContents(document, "//opf:metadata/dc:creator", manager));
-        metadata["language"] = GetFirstTextContent(document, "//opf:metadata/dc:language", manager);
-        metadata["publisher"] = GetFirstTextContent(document, "//opf:metadata/dc:publisher", manager);
-        metadata["date"] = GetFirstTextContent(document, "//opf:metadata/dc:date", manager);
-        metadata["description"] = GetFirstTextContent(document, "//opf:metadata/dc:description", manager);
-        metadata["identifier"] = GetFirstTextContent(document, "//opf:metadata/dc:identifier", manager);
+        metadata[MetadataKeys.EpubTitle] = GetFirstTextContent(document, "//opf:metadata/dc:title", manager);
+        metadata[MetadataKeys.EpubAuthor] = string.Join(", ", GetAllTextContents(document, "//opf:metadata/dc:creator", manager));
+        metadata[MetadataKeys.EpubLanguage] = GetFirstTextContent(document, "//opf:metadata/dc:language", manager);
+        metadata[MetadataKeys.EpubPublisher] = GetFirstTextContent(document, "//opf:metadata/dc:publisher", manager);
+        metadata[MetadataKeys.EpubDate] = GetFirstTextContent(document, "//opf:metadata/dc:date", manager);
+        metadata[MetadataKeys.EpubDescription] = GetFirstTextContent(document, "//opf:metadata/dc:description", manager);
+        metadata[MetadataKeys.EpubIdentifier] = GetFirstTextContent(document, "//opf:metadata/dc:identifier", manager);
 
         return metadata;
     }
@@ -461,7 +461,7 @@ private static EpubExtractionResult BuildExtraction(IReadOnlyList<SectionContent
             var metadata = new Dictionary<string, string>
             {
                 [MetadataKeys.Page] = pageNumber.ToString(CultureInfo.InvariantCulture),
-                ["epub.section"] = section.Label
+                [MetadataKeys.EpubSection] = section.Label
             };
 
             var segment = new DocumentSegment(