@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Rag/DeltaIngest.cs

@@ -0,0 +1,169 @@
+namespace Morph.AiKit.Rag;
+
+/// <summary>
+/// Erro de <b>entrada</b> do <see cref="DeltaIngest"/>: a mesma lookup-key apareceu duas
+/// vezes na mesma remessa.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Nao e fluxo de controle e nao e recuperavel no lugar: com a chave repetida, "o que esta
+/// no acervo" deixa de ter resposta unica e o plano vira nao-deterministico — qual dos dois
+/// itens venceu passa a depender da ordem de enumeracao. Silenciar (ficar com o ultimo)
+/// gravaria um dos dois ao acaso; deduplicar por conta propria esconderia um defeito da
+/// origem, que e onde ele tem conserto.
+/// </para>
+/// <para>
+/// Os dois indices vao na excecao porque "chave X duplicada" manda procurar num corpus de
+/// milhares; "posicoes 12 e 4.871" manda olhar duas linhas.
+/// </para>
+/// </remarks>
+public sealed class DuplicateLookupKeyException : ArgumentException
+{
+    internal DuplicateLookupKeyException(string lookupKey, int firstIndex, int duplicateIndex, string paramName)
+        : base(
+            $"lookup-key duplicada na entrada: '{lookupKey}' aparece nas posicoes {firstIndex} e " +
+            $"{duplicateIndex}. Com a mesma chave em dois itens, o plano de ingestao deixa de ser " +
+            "deterministico — qual dos dois vence passaria a depender da ordem. Corrija a origem " +
+            "ou torne a chave realmente unica.",
+            paramName)
+    {
+        LookupKey = lookupKey;
+        FirstIndex = firstIndex;
+        DuplicateIndex = duplicateIndex;
+    }
+
+    /// <summary>A chave repetida.</summary>
+    public string LookupKey { get; }
+
+    /// <summary>Onde ela apareceu pela primeira vez.</summary>
+    public int FirstIndex { get; }
+
+    /// <summary>Onde ela reapareceu.</summary>
+    public int DuplicateIndex { get; }
+}
+
+/// <summary>
+/// Planejamento de ingestao <b>idempotente por lookup-key</b>: dada uma remessa e o que o
+/// acervo ja tem, diz o que entrou, o que mudou, o que sumiu e o que ficou igual.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Funcao pura, sem I/O.</b> Nao abre conexao, nao chama embedding, nao mede tempo — o
+/// que a torna testavel sem banco e, mais importante, torna a idempotencia <b>demonstravel</b>
+/// em vez de prometida: aplicar o plano e replanejar a mesma entrada tem de devolver
+/// <see cref="DeltaPlan{T}.IsNoOp"/> verdadeiro.
+/// </para>
+/// <para>
+/// <b>A chave e a identidade; o hash e a versao.</b> Sao duas perguntas diferentes e por isso
+/// dois delegados: <c>lookupKey</c> responde "e o mesmo documento?" e <c>contentHash</c>
+/// responde "mudou?". Colapsar as duas num campo so — usar o hash como chave — faz cada
+/// edicao parecer um documento novo e o original parecer removido, que e a ingestao
+/// apaga-tudo com outro nome.
+/// </para>
+/// </remarks>
+public static class DeltaIngest
+{
+    /// <summary>
+    /// Compara a remessa com o acervo e devolve o plano.
+    /// </summary>
+    /// <typeparam name="T">O item ingerido.</typeparam>
+    /// <param name="incoming">A remessa. Enumerada uma unica vez.</param>
+    /// <param name="lookupKey">
+    /// A identidade estavel do item — o que faz duas versoes do mesmo documento serem o
+    /// mesmo documento. Nula ou em branco e recusada: uma chave vazia colapsaria itens
+    /// distintos num so.
+    /// </param>
+    /// <param name="contentHash">
+    /// A versao do conteudo. Igual significa "nao mudou"; diferente significa "mudou". Nulo e
+    /// recusado — sem hash nao ha como distinguir <c>Unchanged</c> de <c>Updated</c>, e
+    /// tratar a ausencia como "mudou" reintroduziria o re-embedding de tudo.
+    /// </param>
+    /// <param name="existingHashes">
+    /// O que o acervo tem hoje: lookup-key para hash de conteudo. As chaves daqui que nao
+    /// aparecerem na remessa saem em <see cref="DeltaPlan{T}.Removed"/>.
+    /// </param>
+    /// <exception cref="DuplicateLookupKeyException">A mesma chave veio duas vezes.</exception>
+    /// <exception cref="ArgumentException">Um item produziu chave ou hash nulo/em branco.</exception>
+    public static DeltaPlan<T> Plan<T>(
+        IEnumerable<T> incoming,
+        Func<T, string> lookupKey,
+        Func<T, string> contentHash,
+        IReadOnlyDictionary<string, string> existingHashes)
+    {
+        ArgumentNullException.ThrowIfNull(incoming);
+        ArgumentNullException.ThrowIfNull(lookupKey);
+        ArgumentNullException.ThrowIfNull(contentHash);
+        ArgumentNullException.ThrowIfNull(existingHashes);
+
+        List<T> added = [];
+        List<T> updated = [];
+        List<T> unchanged = [];
+
+        // Comparacao ordinal, explicita: a chave e um identificador, nao texto de usuario.
+        // Deixar a cultura decidir faria o mesmo corpus produzir planos diferentes conforme a
+        // maquina que roda a ingestao.
+        var seen = new Dictionary<string, int>(StringComparer.Ordinal);
+        var index = 0;
+
+        foreach (var item in incoming)
+        {
+            var key = lookupKey(item);
+
+            if (string.IsNullOrWhiteSpace(key))
+            {
+                throw new ArgumentException(
+                    $"o item na posicao {index} produziu uma lookup-key vazia. Sem identidade nao " +
+                    "ha como saber se ele ja esta no acervo, e itens distintos colapsariam num so.",
+                    nameof(lookupKey));
+            }
+
+            if (seen.TryGetValue(key, out var firstIndex))
+            {
+                throw new DuplicateLookupKeyException(key, firstIndex, index, nameof(incoming));
+            }
+
+            seen.Add(key, index);
+
+            var hash = contentHash(item);
+
+            if (string.IsNullOrWhiteSpace(hash))
+            {
+                throw new ArgumentException(
+                    $"o item '{key}' (posicao {index}) produziu um hash de conteudo vazio. Sem " +
+                    "versao nao ha como distinguir 'nao mudou' de 'mudou', e a ingestao voltaria " +
+                    "a reprocessar tudo a cada rodada.",
+                    nameof(contentHash));
+            }
+
+            if (!existingHashes.TryGetValue(key, out var knownHash))
+            {
+                added.Add(item);
+            }
+            else if (string.Equals(knownHash, hash, StringComparison.Ordinal))
+            {
+                unchanged.Add(item);
+            }
+            else
+            {
+                updated.Add(item);
+            }
+
+            index++;
+        }
+
+        // O que o acervo tem e a remessa nao trouxe. Note que 'seen' e consultado pela MESMA
+        // chave e com o MESMO comparador usados acima — uma segunda nocao de igualdade aqui
+        // faria itens presentes serem reportados como removidos.
+        List<string> removed = [];
+
+        foreach (var key in existingHashes.Keys)
+        {
+            if (!seen.ContainsKey(key))
+            {
+                removed.Add(key);
+            }
+        }
+
+        return new DeltaPlan<T>(added, updated, removed, unchanged);
+    }
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Rag/DeltaPlan.cs

@@ -0,0 +1,49 @@
+namespace Morph.AiKit.Rag;
+
+/// <summary>
+/// O que precisa acontecer no acervo para que ele passe a refletir a entrada — e nada mais.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>O defeito que este tipo existe para matar</b> e concreto e esta em producao: a base de
+/// conhecimento do GHLBrain <b>apaga tudo e re-embeda tudo</b> a cada ingestao. O custo e
+/// pago em embedding de documento que nao mudou, e a janela entre o apagar e o gravar e uma
+/// janela em que a busca nao acha nada. Um plano em quatro baldes torna visivel o que a
+/// ingestao inteira escondia: quase sempre <see cref="Unchanged"/> e a lista grande e as
+/// outras tres sao curtas.
+/// </para>
+/// <para>
+/// <b>E um plano, nao uma execucao.</b> Nada aqui toca banco, vetor ou arquivo: quem aplica
+/// e o projeto, que sabe qual e a sua transacao. E por isso que a idempotencia da ingestao
+/// pode ser provada sem subir infraestrutura nenhuma.
+/// </para>
+/// </remarks>
+/// <typeparam name="T">O item ingerido — documento, trecho, linha.</typeparam>
+/// <param name="Added">Itens cuja chave nao existia no acervo.</param>
+/// <param name="Updated">Itens cuja chave existia com <b>outro</b> conteudo.</param>
+/// <param name="Removed">
+/// Chaves que estavam no acervo e <b>nao vieram</b> na entrada. Sao chaves, e nao itens:
+/// o que sumiu da origem nao tem corpo para carregar.
+/// </param>
+/// <param name="Unchanged">
+/// Itens cuja chave existia com o <b>mesmo</b> conteudo. Nao re-embedar estes e a economia
+/// inteira desta feature.
+/// </param>
+public sealed record DeltaPlan<T>(
+    IReadOnlyList<T> Added,
+    IReadOnlyList<T> Updated,
+    IReadOnlyList<string> Removed,
+    IReadOnlyList<T> Unchanged)
+{
+    /// <summary>Plano vazio — nem entrada, nem acervo.</summary>
+    public static DeltaPlan<T> Empty { get; } = new([], [], [], []);
+
+    /// <summary>
+    /// Se o acervo ja reflete a entrada. <b>E a idempotencia expressa como predicado:</b>
+    /// re-planejar a mesma entrada sobre o acervo que ela produziu tem de dar verdadeiro.
+    /// </summary>
+    public bool IsNoOp => Added.Count == 0 && Updated.Count == 0 && Removed.Count == 0;
+
+    /// <summary>Quantos itens da entrada tocam o acervo. Zero num plano idempotente.</summary>
+    public int WriteCount => Added.Count + Updated.Count + Removed.Count;
+}