Improve Per-extractor Instructions

.vscode/launch.json

@@ -0,0 +1,13 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Local",
+      "type": "coreclr",
+      "request": "launch",
+      "program": "${workspaceFolder}/src/Elzik.Breef.Api/bin/Debug/net8.0/Elzik.Breef.Api.dll",
+      "cwd": "${workspaceFolder}/src/Elzik.Breef.Api",
+      "stopAtEntry": false
+    }
+  ]
+}

README.md

@@ -145,4 +145,15 @@ Logging is handled by Serilog and configuration is documented [here](https://git
   "MinimumLevel": {
     "Default": "Debug"   // breef_Serilog__MinimumLevel__Default
   }
-}
+}
+```
+
+#### Time Zone
+
+By default, the Docker container for the Breef API uses the UTC time zone. If you need to set a specific time zone for the application running in the container, set the `TZ` environment variable when building or running the container. For example:
+
+```sh
+docker run -e TZ=Europe/London ...
+```
+
+Replace `Europe/London` with your desired time zone identifier. A [comprehensive list can be found in Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

src/Elzik.Breef.Application/BreefGenerator.cs

@@ -16,7 +16,7 @@ public async Task<PublishedBreef> GenerateBreefAsync(string url)
 
             var summary = await contentSummariser.SummariseAsync(extract.Content, instructions);
 
-            var breef = new Domain.Breef(url, extract.Title, summary, extract.PreviewImageUrl);
+            var breef = new Domain.Breef(extract.OriginalUrl, extract.Title, summary, extract.PreviewImageUrl);
 
             var publishedBreef = await breefPublisher.PublishAsync(breef);
 

src/Elzik.Breef.Domain/Extract.cs

@@ -1,3 +1,8 @@
 namespace Elzik.Breef.Domain;
 
-public record Extract(string Title, string Content, string? PreviewImageUrl, string ExtractType);
+public record Extract(
+    string Title, 
+    string Content,
+    string OriginalUrl, 
+    string? PreviewImageUrl, 
+    string ExtractType);

src/Elzik.Breef.Infrastructure/CallerFixableHttpRequestException.cs

@@ -2,11 +2,8 @@
 
 namespace Elzik.Breef.Infrastructure
 {
-    public class CallerFixableHttpRequestException : HttpRequestException, ICallerFixableException
+    public class CallerFixableHttpRequestException(string message, Exception? innerException = null) 
+        : HttpRequestException(message, innerException), ICallerFixableException
     {
-        public CallerFixableHttpRequestException(string message, Exception? innerException = null)
-            : base(message, innerException)
-        {
-        }
     }
 }

src/Elzik.Breef.Infrastructure/ContentExtractors/HtmlContentExtractor.cs

@@ -31,8 +31,7 @@ protected override async Task<UntypedExtract> CreateUntypedExtractAsync(string w
         var title = GetTitle(htmlDocument, webPageUrl);
         var largestImageUrl = GetLargestImageUrl(htmlDocument);
 
-
-        return new UntypedExtract(title, content, largestImageUrl);
+        return new UntypedExtract(title, content, webPageUrl, largestImageUrl);
     }
 
     private static string GetContent(HtmlDocument htmlDocument)

src/Elzik.Breef.Infrastructure/ContentExtractors/Reddit/Client/Raw/RawRedditPostTransformer.cs

@@ -1,43 +1,21 @@
 using System.Text.Json;
 using System.Web;
+using Microsoft.Extensions.Options;
 
 namespace Elzik.Breef.Infrastructure.ContentExtractors.Reddit.Client.Raw;
 
 public class RawRedditPostTransformer : IRawRedditPostTransformer
 {
-    public RedditPost Transform(RawRedditPost rawRedditPost)
-    {
-        ArgumentNullException.ThrowIfNull(rawRedditPost);
-        if (rawRedditPost.Count < 2)
-            throw new ArgumentException("Reddit post must have at least 2 listings (post and comments)", nameof(rawRedditPost));
+    private readonly RedditOptions _options;
 
-        var postListing = rawRedditPost[0];
-        var commentsListing = rawRedditPost[1];
-
-        var postChildren = postListing.Data?.Children;
-        if (postChildren == null || postChildren.Count == 0)
-            throw new ArgumentException("Post listing must contain at least one child", nameof(rawRedditPost));
+    public RawRedditPostTransformer(IOptions<RedditOptions> options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
 
-        var mainPostData = postChildren[0].Data;
-        var bestImage = ExtractBestImage(mainPostData);
+        if (options.Value == null)
+            throw new InvalidOperationException("RedditOptions configuration is missing or not bound.");
 
-        var redditPost = new RedditPost
-        {
-            Post = new RedditPostContent
-            {
-                Id = mainPostData.Id ?? string.Empty,
-                Title = mainPostData.Title ?? throw new InvalidOperationException("Reddit post must have a title"),
-                Author = mainPostData.Author ?? string.Empty,
-                Subreddit = mainPostData.Subreddit ?? string.Empty,
-                Score = mainPostData.Score,
-                Content = mainPostData.Content ?? string.Empty,
-                CreatedUtc = mainPostData.CreatedUtc,
-                ImageUrl = bestImage
-            },
-            Comments = TransformComments(commentsListing)
-        };
-
-        return redditPost;
+        _options = options.Value;
     }
 
     private static string? ExtractBestImage(RawRedditCommentData postData)
@@ -91,7 +69,6 @@ public RedditPost Transform(RawRedditPost rawRedditPost)
 
         return null;
     }
-
     private static bool IsImageUrl(string? url)
     {
         if (string.IsNullOrEmpty(url))
@@ -104,22 +81,24 @@ private static bool IsImageUrl(string? url)
         return extension is ".jpg" or ".jpeg" or ".png" or ".gif" or ".webp" or ".bmp" or ".svg";
     }
 
-    private List<RedditComment> TransformComments(List<RawRedditChild> children)
+    private List<RedditComment> TransformComments(List<RawRedditChild> children, string subreddit, string postId, string host)
     {
         var comments = new List<RedditComment>();
 
         foreach (var child in children)
         {
             if (child.Kind == "t1")
             {
+                var commentUrl = $"https://{host}/r/{subreddit}/comments/{postId}/comment/{child.Data.Id}/";
                 var comment = new RedditComment
                 {
                     Id = child.Data.Id ?? string.Empty,
                     Author = child.Data.Author ?? string.Empty,
                     Score = child.Data.Score,
                     Content = child.Data.Content ?? string.Empty,
                     CreatedUtc = child.Data.CreatedUtc,
-                    Replies = TransformComments(child.Data.Replies)
+                    PostUrl = commentUrl,
+                    Replies = TransformComments(child.Data.Replies, subreddit, postId, host)
                 };
 
                 comments.Add(comment);
@@ -129,7 +108,7 @@ private List<RedditComment> TransformComments(List<RawRedditChild> children)
         return comments;
     }
 
-    private List<RedditComment> TransformComments(object? replies)
+    private List<RedditComment> TransformComments(object? replies, string subreddit, string postId, string host)
     {
         if (replies == null)
             return [];
@@ -148,7 +127,7 @@ private List<RedditComment> TransformComments(object? replies)
             try
             {
                 var deserializedListing = JsonSerializer.Deserialize<RawRedditListing>(jsonElement.GetRawText());
-                return TransformComments(deserializedListing);
+                return TransformComments(deserializedListing, subreddit, postId, host);
             }
             catch
             {
@@ -157,12 +136,12 @@ private List<RedditComment> TransformComments(object? replies)
         }
 
         if (replies is RawRedditListing listing)
-            return TransformComments(listing);
+            return TransformComments(listing, subreddit, postId, host);
 
         return [];
     }
 
-    private List<RedditComment> TransformComments(RawRedditListing? replies)
+    private List<RedditComment> TransformComments(RawRedditListing? replies, string subreddit, string postId, string host)
     {
         if (replies == null)
             return [];
@@ -173,6 +152,51 @@ private List<RedditComment> TransformComments(RawRedditListing? replies)
         if (replies.Data.Children == null)
             return [];
 
-        return TransformComments(replies.Data.Children);
+        return TransformComments(replies.Data.Children, subreddit, postId, host);
+    }
+
+    public RedditPost Transform(RawRedditPost rawRedditPost)
+    {
+        ArgumentNullException.ThrowIfNull(rawRedditPost);
+        if (rawRedditPost.Count < 2)
+            throw new ArgumentException("Reddit post must have at least 2 listings (post and comments)", nameof(rawRedditPost));
+
+        var postListing = rawRedditPost[0];
+        var commentsListing = rawRedditPost[1];
+
+        var postChildren = postListing.Data?.Children;
+        if (postChildren == null || postChildren.Count == 0)
+            throw new ArgumentException("Post listing must contain at least one child", nameof(rawRedditPost));
+
+        var mainPostData = postChildren[0].Data;
+        var bestImage = ExtractBestImage(mainPostData);
+
+        var subreddit = mainPostData.Subreddit ?? string.Empty;
+        var postId = mainPostData.Id ?? string.Empty;
+        var postUrl = mainPostData.Url ?? string.Empty;
+
+        if (!Uri.TryCreate(_options.DefaultBaseAddress, UriKind.Absolute, out var defaultUri))
+        {
+            throw new InvalidOperationException("RedditOptions.DefaultBaseAddress is not a valid absolute URI");
+        }
+
+        var redditPost = new RedditPost
+        {
+            Post = new RedditPostContent
+            {
+                Id = mainPostData.Id ?? string.Empty,
+                Title = mainPostData.Title ?? throw new InvalidOperationException("Reddit post must have a title"),
+                Author = mainPostData.Author ?? string.Empty,
+                Subreddit = subreddit,
+                Score = mainPostData.Score,
+                Content = mainPostData.Content ?? string.Empty,
+                CreatedUtc = mainPostData.CreatedUtc,
+                ImageUrl = bestImage,
+                PostUrl = postUrl
+            },
+            Comments = TransformComments(commentsListing.Data?.Children ?? [], subreddit, postId, defaultUri.Host)
+        };
+
+        return redditPost;
     }
 }

src/Elzik.Breef.Infrastructure/ContentExtractors/Reddit/Client/RedditPost.cs

@@ -16,6 +16,7 @@ public class RedditPostContent
     public string Content { get; set; } = string.Empty;
     public DateTime CreatedUtc { get; set; }
     public string? ImageUrl { get; set; }
+    public string PostUrl { get; set; } = string.Empty;
 }
 
 public class RedditComment
@@ -26,4 +27,5 @@ public class RedditComment
     public string Content { get; set; } = string.Empty;
     public DateTime CreatedUtc { get; set; }
     public List<RedditComment> Replies { get; set; } = [];
+    public string PostUrl { get; set; } = string.Empty;
 }

src/Elzik.Breef.Infrastructure/ContentExtractors/Reddit/RedditPostContentExtractor.cs

@@ -60,6 +60,7 @@ protected override async Task<UntypedExtract> CreateUntypedExtractAsync(string w
 
         var postId = segments[3];
         var post = await redditPostClient.GetPost(postId);
+        post.Post.PostUrl = webPageUrl;
 
         if (string.IsNullOrWhiteSpace(post.Post.ImageUrl))
         {
@@ -69,6 +70,6 @@ protected override async Task<UntypedExtract> CreateUntypedExtractAsync(string w
 
         var postJson = JsonSerializer.Serialize(post);
 
-        return new UntypedExtract(post.Post.Title, postJson, post.Post.ImageUrl);
+        return new UntypedExtract(post.Post.Title, postJson, webPageUrl, post.Post.ImageUrl);
     }
 }

src/Elzik.Breef.Infrastructure/ContentExtractors/Reddit/SubRedditContentExtractor.cs

@@ -8,6 +8,7 @@ namespace Elzik.Breef.Infrastructure.ContentExtractors.Reddit;
 public class SubredditContentExtractor(
     ISubredditClient subredditClient,
     IHttpClientFactory httpClientFactory,
+    TimeProvider timeProvider,
     IOptions<RedditOptions> redditOptions)
     : ContentExtractorBase, ISubredditImageExtractor
 {
@@ -43,7 +44,11 @@ protected override async Task<UntypedExtract> CreateUntypedExtractAsync(string w
         var jsonContent = JsonSerializer.Serialize(newInSubreddit);
         var imageUrl = await ExtractImageUrlAsync(webPageUri);
 
-        return new UntypedExtract($"New in r/{subredditName}", jsonContent, imageUrl);
+        var dateAndTime = timeProvider.GetLocalNow().ToString("yyyy-MM-dd HH:mm");
+        var title = $"New in r/{subredditName} as of {dateAndTime}";
+        var instanceSpecificOriginalUrl = $"{webPageUrl}#{dateAndTime}";
+
+        return new UntypedExtract(title, jsonContent, instanceSpecificOriginalUrl, imageUrl);
     }
 
     public async Task<string> GetSubredditImageUrlAsync(string subredditName)

src/Elzik.Breef.Infrastructure/ContentExtractors/UntypedExtract.cs

@@ -2,8 +2,8 @@
 
 namespace Elzik.Breef.Infrastructure.ContentExtractors;
 
-public record UntypedExtract(string Title, string Content, string? PreviewImageUrl)
+public record UntypedExtract(string Title, string Content, string OriginalUrl, string? PreviewImageUrl)
 {
     public Extract WithType(string extractType) 
-        => new(Title, Content, PreviewImageUrl, extractType);
+        => new(Title, Content, OriginalUrl, PreviewImageUrl, extractType);
 }

src/Elzik.Breef.Infrastructure/SummarisationInstructions/HtmlContent.md

@@ -1,8 +1,24 @@
-You are an expert summarizer. Your task is to summarize the provided text:
-- Summarise text, including HTML entities.
-- Limit summaries to 10% of the original length but never more than 200 words.
-- Ensure accurate attribution of information to the correct entities.
-- Do not include a link to the original article.
-- Do not include the title in the response.
-- Do not include any metadata in the response.
-- Do not include a code block in the response.
+# Task
+
+Summarise the provided web page text.
+
+## Input Structure
+
+The provided text is the main content extracted from a web page.
+
+## Requirements
+
+1. **Overview**
+   - Summarise text, including HTML entities.
+   - Limit summaries to 10% of the original length but never more than 200 words.
+   - Ensure accurate attribution of information to the correct entities.
+2. **Exclude**
+   - Links to original article
+   - Web page title
+   - Metadata
+   - Code blocks
+
+## Output Formatting
+
+- Strictly well-formatted HTML output
+- Do not include any markdown notation nor put the summary in a codeblock

src/Elzik.Breef.Infrastructure/SummarisationInstructions/RedditPostContent.md

@@ -1,8 +1,30 @@
-You are an expert summarizer. Your task is to summarize the provided text:
- - Summarise text, including HTML entities.
- - Limit summaries to 10% of the original length but never more then 200 words.
- - Ensure accurate attribution of information to the correct entities.
- - Do not include a link to the original articles.
- - Do not include the title in the response.
- - Do not include any metadata in the response.
- - Do not include a code block in the response.
+# Task
+
+Summarise the provided Reddit post JSON data containing a single post and its nested comments.
+
+## Input Structure
+
+JSON with a top-level "Post" item containing:
+- Metadata: Title, Author, Subreddit, Score, Content, CreatedUtc, PostUrl
+- Comments: Array with Author, Score, Content, CreatedUtc, PostUrl and nested Replies
+
+## Requirements
+
+1. **Overview**: Describe the general state/themes of the Reddit post
+2. **Top Level Post**: Summarise the top-level post in detail
+3. **Replies**: Summarise only the highest-scoring replies in lower detail
+4. **Summaries**: 
+   - Maximum 200 words OR 10% of original length (whichever is shorter)
+   - For a top-level post, include post title as HTML link to the post URL: `<a href="RedditPostContent.PostUrl" target="_blank" rel="noopener noreferrer">Title</a>`
+   - For a post's highest-scoring replies, also summarise them and include author attribution with comment links: `<a href="RedditComment.PostUrl" target="_blank" rel="noopener noreferrer">@author</a>`. Link to the author's comment, not to the author's profile.
+5. **Exclude**:
+   - Links to Subreddit
+   - Root post title
+   - Metadata timestamps/scores
+   - Code blocks
+   - General description of the subreddit itself
+
+## Output Formatting
+
+- Strictly well-formatted HTML output
+- Do not include any markdown notation nor put the summary in a codeblock