Docs + Phase D+: optional server-side automatic web search (off by default)

README fully rewritten to cover both tools (AI-writing linter + Originality
checker A–D), the predictability meter, current architecture, and the optional
web-search configuration.

Phase D+ — an optional automatic web spot-check for presentations, OFF unless
the operator configures it (the on-device one-click searches remain the default):
- Server: WebSearchOptions ("WebSearch" section, disabled by default; key from
  config or BRAVE_API_KEY env — the key never touches the browser).
  WebSearchService + BraveSearchProvider (provider-abstracted), POST /api/webcheck,
  and GET / advertises webSearchReady. Quota guards: per-phrase cache, caps on
  phrases/doc and results/phrase, and verbatim verification so only genuine
  matches are badged.
- Client: WebCheckClient + an "Auto web search: ON" panel that appears only when
  the server advertises the capability; hits show URL, snippet and a verbatim
  badge. Fail-safe: disabled/quota/error falls back to the manual one-click
  searches — it never breaks.

No secrets committed (feature ships disabled). Client is safe to deploy as-is;
the server feature stays inert until an operator sets a key + redeploys.
Full suite 40/40 green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: peopleworks

README.md

@@ -0,0 +1,33 @@
+namespace SignsOfAI.Perplexity.Api.Config;
+
+/// <summary>
+/// Config for the <b>optional</b> automatic web spot-check (Phase D+). It is <b>off unless configured</b>:
+/// the on-device, one-click-search experience is the default. When an operator supplies a search provider
+/// and key (here or via the <c>BRAVE_API_KEY</c> environment variable — the key never touches the browser),
+/// the server can automatically report web pages that contain a passage verbatim. Useful for live demos /
+/// presentations; kept behind config so the hosted default stays dependency-free.
+/// </summary>
+public sealed class WebSearchOptions
+{
+    /// <summary>Master switch. Even when true, the feature only activates if a key resolves.</summary>
+    public bool Enabled { get; init; }
+
+    /// <summary>Search provider. Currently "brave" (Brave Search API); provider-abstracted for others.</summary>
+    public string Provider { get; init; } = "brave";
+
+    /// <summary>API key. Prefer the environment variable over committing it to appsettings.</summary>
+    public string? ApiKey { get; init; }
+
+    /// <summary>Cap on how many distinctive phrases we search per document (quota control for live demos).</summary>
+    public int MaxPhrasesPerDoc { get; init; } = 8;
+
+    /// <summary>Cap on results returned per phrase.</summary>
+    public int MaxResultsPerPhrase { get; init; } = 5;
+
+    /// <summary>The key from config, falling back to the BRAVE_API_KEY environment variable.</summary>
+    public string? ResolveKey() =>
+        !string.IsNullOrWhiteSpace(ApiKey) ? ApiKey : Environment.GetEnvironmentVariable("BRAVE_API_KEY");
+
+    /// <summary>The feature is genuinely usable (enabled AND a key is present).</summary>
+    public bool IsActive => Enabled && !string.IsNullOrWhiteSpace(ResolveKey());
+}

src/SignsOfAI.Perplexity.Api/Config/WebSearchOptions.cs

@@ -72,6 +72,39 @@ public sealed record ServiceInfo
     public bool EmbeddingReady { get; init; }
     /// <summary>Selectable embedding models (for the paraphrase check). Empty when the feature is off.</summary>
     public ModelInfo[] EmbeddingModels { get; init; } = [];
+    /// <summary>The operator has configured an automatic web search (Phase D+). Off by default.</summary>
+    public bool WebSearchReady { get; init; }
+}
+
+/// <summary>One web page returned for a searched phrase.</summary>
+public sealed record WebHit
+{
+    public string Url { get; init; } = "";
+    public string Title { get; init; } = "";
+    public string Snippet { get; init; } = "";
+    /// <summary>The returned snippet visibly contains the phrase (strong evidence, not just a loose match).</summary>
+    public bool Verbatim { get; init; }
+}
+
+/// <summary>The web hits found for one distinctive phrase.</summary>
+public sealed record PhraseHits
+{
+    public string Phrase { get; init; } = "";
+    public WebHit[] Hits { get; init; } = [];
+}
+
+/// <summary>Request body for POST /api/webcheck.</summary>
+public sealed record WebCheckRequest
+{
+    /// <summary>Distinctive phrases to look up on the web (exact-phrase). Required, non-empty.</summary>
+    public string[] Phrases { get; init; } = [];
+}
+
+/// <summary>Response body for POST /api/webcheck.</summary>
+public sealed record WebCheckResponse
+{
+    public PhraseHits[] Results { get; init; } = [];
+    public long ElapsedMs { get; init; }
 }
 
 /// <summary>Request body for POST /api/embed — the paraphrase/semantic-similarity embedding endpoint.</summary>
@@ -106,4 +139,6 @@ public sealed record EmbedResponse
 [JsonSerializable(typeof(EmbedRequest))]
 [JsonSerializable(typeof(EmbedResponse))]
 [JsonSerializable(typeof(float[][]))]
+[JsonSerializable(typeof(WebCheckRequest))]
+[JsonSerializable(typeof(WebCheckResponse))]
 public partial class ApiJsonContext : JsonSerializerContext;

src/SignsOfAI.Perplexity.Api/Model/Contracts.cs

@@ -22,6 +22,11 @@
 builder.Services.AddSingleton<EmbeddingRegistry>();
 builder.Services.AddHostedService<EmbeddingLifecycleService>();
 
+// ── Optional automatic web spot-check (Phase D+) — inert unless an operator configured a provider + key ──
+var webSearchOptions = builder.Configuration.GetSection("WebSearch").Get<WebSearchOptions>() ?? new WebSearchOptions();
+builder.Services.AddSingleton(webSearchOptions);
+builder.Services.AddSingleton<SignsOfAI.Perplexity.Api.Search.WebSearchService>();
+
 // Source-generated JSON so we stay trim/AOT-friendly.
 builder.Services.Configure<JsonOptions>(o =>
     o.SerializerOptions.TypeInfoResolverChain.Insert(0, ApiJsonContext.Default));
@@ -36,7 +41,7 @@
 app.UseCors();
 
 // ── Endpoints ─────────────────────────────────────────────────────────────────
-app.MapGet("/", (PerplexityRegistry reg, EmbeddingRegistry embed) => Results.Ok(new ServiceInfo
+app.MapGet("/", (PerplexityRegistry reg, EmbeddingRegistry embed, SignsOfAI.Perplexity.Api.Search.WebSearchService web) => Results.Ok(new ServiceInfo
 {
     ModelReady = reg.Default.FilesReady,
     Languages = [.. reg.Default.Profile.Baselines.Keys],
@@ -51,6 +56,7 @@
         Id = e.ModelId, Label = e.Profile.Label, Note = e.Profile.Note,
         IsDefault = e == embed.Default, Loaded = e.IsLoaded,
     })],
+    WebSearchReady = web.IsActive,
 }));
 
 app.MapGet("/healthz", (PerplexityRegistry reg) =>
@@ -127,4 +133,16 @@
     }
 });
 
+// ── Optional automatic web spot-check (Phase D+) ──
+app.MapPost("/api/webcheck", async (WebCheckRequest req, SignsOfAI.Perplexity.Api.Search.WebSearchService web, CancellationToken ct) =>
+{
+    if (!web.IsActive) return Results.Json(new { enabled = false }, statusCode: 404);
+    if (req.Phrases is null || req.Phrases.Length == 0)
+        return Results.BadRequest(new { error = "phrases is required" });
+
+    var sw = System.Diagnostics.Stopwatch.StartNew();
+    var results = await web.CheckAsync(req.Phrases, ct);
+    return Results.Ok(new WebCheckResponse { Results = [.. results], ElapsedMs = sw.ElapsedMilliseconds });
+});
+
 app.Run();

src/SignsOfAI.Perplexity.Api/Program.cs

@@ -0,0 +1,158 @@
+using System.Collections.Concurrent;
+using System.Globalization;
+using System.Text;
+using System.Text.Json;
+using SignsOfAI.Perplexity.Api.Config;
+using SignsOfAI.Perplexity.Api.Model;
+
+namespace SignsOfAI.Perplexity.Api.Search;
+
+/// <summary>A search backend that finds web pages for an exact phrase.</summary>
+public interface IWebSearchProvider
+{
+    Task<IReadOnlyList<WebHit>> SearchAsync(string phrase, int count, CancellationToken ct);
+}
+
+/// <summary>
+/// Orchestrates the optional automatic web spot-check: caps how much we search (quota safety for live
+/// demos), caches per-phrase results in memory so re-runs don't burn quota, and verifies whether each
+/// returned snippet actually contains the phrase so we only badge genuine verbatim matches. Entirely
+/// inert unless an operator configured a provider + key (see <see cref="WebSearchOptions"/>).
+/// </summary>
+public sealed class WebSearchService
+{
+    private readonly WebSearchOptions _options;
+    private readonly IWebSearchProvider? _provider;
+    private readonly ConcurrentDictionary<string, IReadOnlyList<WebHit>> _cache = new();
+
+    public WebSearchService(WebSearchOptions options, ILogger<WebSearchService> log)
+    {
+        _options = options;
+        if (!options.IsActive) return;
+        var key = options.ResolveKey()!;
+        _provider = options.Provider.ToLowerInvariant() switch
+        {
+            "brave" => new BraveSearchProvider(key, log),
+            _ => new BraveSearchProvider(key, log), // default provider; abstracted for others
+        };
+    }
+
+    public bool IsActive => _provider is not null;
+
+    public async Task<IReadOnlyList<PhraseHits>> CheckAsync(IReadOnlyList<string> phrases, CancellationToken ct)
+    {
+        if (_provider is null) return [];
+        var results = new List<PhraseHits>();
+        foreach (var raw in phrases.Take(_options.MaxPhrasesPerDoc))
+        {
+            var phrase = (raw ?? "").Trim();
+            if (phrase.Length < 8) continue; // too short to be a meaningful fingerprint
+            ct.ThrowIfCancellationRequested();
+
+            if (!_cache.TryGetValue(phrase, out var hits))
+            {
+                var found = await _provider.SearchAsync(phrase, _options.MaxResultsPerPhrase, ct);
+                hits = found.Select(h => h with { Verbatim = SnippetContains(h, phrase) }).ToArray();
+                _cache[phrase] = hits;
+            }
+            results.Add(new PhraseHits { Phrase = phrase, Hits = [.. hits] });
+        }
+        return results;
+    }
+
+    /// <summary>True when the hit's snippet/title visibly contains the phrase (accent/case-insensitive).</summary>
+    private static bool SnippetContains(WebHit hit, string phrase)
+    {
+        var hay = Fold(hit.Snippet + " " + hit.Title);
+        return hay.Contains(Fold(phrase), StringComparison.Ordinal);
+    }
+
+    internal static string Fold(string s)
+    {
+        var sb = new StringBuilder(s.Length);
+        foreach (var c in s.ToLowerInvariant().Normalize(NormalizationForm.FormD))
+            if (CharUnicodeInfo.GetUnicodeCategory(c) != UnicodeCategory.NonSpacingMark)
+                sb.Append(char.IsWhiteSpace(c) ? ' ' : c);
+        // collapse runs of spaces
+        var collapsed = new StringBuilder(sb.Length);
+        bool prevSpace = false;
+        foreach (var c in sb.ToString())
+        {
+            if (c == ' ') { if (!prevSpace) collapsed.Append(' '); prevSpace = true; }
+            else { collapsed.Append(c); prevSpace = false; }
+        }
+        return collapsed.ToString().Trim();
+    }
+}
+
+/// <summary>Brave Search API provider. Queries the exact (quoted) phrase and returns the web results.</summary>
+public sealed class BraveSearchProvider : IWebSearchProvider
+{
+    private static readonly HttpClient Http = new() { Timeout = TimeSpan.FromSeconds(12) };
+    private readonly string _apiKey;
+    private readonly ILogger _log;
+
+    public BraveSearchProvider(string apiKey, ILogger log) { _apiKey = apiKey; _log = log; }
+
+    public async Task<IReadOnlyList<WebHit>> SearchAsync(string phrase, int count, CancellationToken ct)
+    {
+        try
+        {
+            var q = Uri.EscapeDataString("\"" + phrase + "\"");
+            var url = $"https://api.search.brave.com/res/v1/web/search?q={q}&count={Math.Clamp(count, 1, 20)}";
+            using var req = new HttpRequestMessage(HttpMethod.Get, url);
+            req.Headers.TryAddWithoutValidation("X-Subscription-Token", _apiKey);
+            req.Headers.TryAddWithoutValidation("Accept", "application/json");
+
+            using var resp = await Http.SendAsync(req, ct);
+            if (!resp.IsSuccessStatusCode)
+            {
+                _log.LogWarning("Brave search returned {Status} for a phrase query.", (int)resp.StatusCode);
+                return [];
+            }
+
+            await using var stream = await resp.Content.ReadAsStreamAsync(ct);
+            using var doc = await JsonDocument.ParseAsync(stream, cancellationToken: ct);
+            if (!doc.RootElement.TryGetProperty("web", out var web) ||
+                !web.TryGetProperty("results", out var results) || results.ValueKind != JsonValueKind.Array)
+                return [];
+
+            var hits = new List<WebHit>();
+            foreach (var r in results.EnumerateArray())
+            {
+                var u = Str(r, "url");
+                if (string.IsNullOrWhiteSpace(u)) continue;
+                hits.Add(new WebHit
+                {
+                    Url = u,
+                    Title = StripHtml(Str(r, "title")),
+                    Snippet = StripHtml(Str(r, "description")),
+                });
+                if (hits.Count >= count) break;
+            }
+            return hits;
+        }
+        catch (Exception ex)
+        {
+            _log.LogWarning(ex, "Brave search failed; falling back to no results.");
+            return [];
+        }
+    }
+
+    private static string Str(JsonElement e, string prop) =>
+        e.TryGetProperty(prop, out var v) && v.ValueKind == JsonValueKind.String ? v.GetString() ?? "" : "";
+
+    private static string StripHtml(string s)
+    {
+        if (string.IsNullOrEmpty(s) || s.IndexOf('<') < 0) return s;
+        var sb = new StringBuilder(s.Length);
+        bool inTag = false;
+        foreach (var c in s)
+        {
+            if (c == '<') inTag = true;
+            else if (c == '>') inTag = false;
+            else if (!inTag) sb.Append(c);
+        }
+        return sb.ToString();
+    }
+}