Merge pull request #117 from isartor-ai/feat-176-rag

feat(agents): knowledge retrieval (RAG) tool for agents (#176)

Author: robinson

src/Autofac.Agents/DependencyInjection.cs

@@ -31,6 +31,9 @@ public static IServiceCollection AddAutofacAgents(
         services.AddScoped<IAgentTool, GitHubPostReviewTool>();
         services.AddScoped<IAgentTool, CicdTriggerDeployTool>();
         services.AddScoped<IAgentTool, SandboxExecutionTool>();
+        services.Configure<Knowledge.KnowledgeOptions>(configuration.GetSection(Knowledge.KnowledgeOptions.Section));
+        services.AddSingleton<Knowledge.IKnowledgeRetriever, Knowledge.LexicalKnowledgeRetriever>();
+        services.AddScoped<IAgentTool, KnowledgeSearchTool>();
         services.AddScoped<IAgentHookHandler, InternalPolicyHookHandler>();
         services.AddScoped<IAgentHookHandler, TemplateHookHandler>();
         services.AddScoped<IAgentHookGateway, HookGateway>();

src/Autofac.Agents/Knowledge/KnowledgeRetriever.cs

@@ -0,0 +1,91 @@
+using Microsoft.Extensions.Options;
+
+namespace Autofac.Agents.Knowledge;
+
+public sealed record KnowledgeDocument(string Source, string Text);
+
+public sealed record KnowledgeSnippet(string Source, string Text, double Score);
+
+/// <summary>
+/// Retrieves context relevant to a query, with provenance, for agents to ground on (#176).
+/// The backing store is pluggable — a lexical corpus today, a vector/embeddings store later.
+/// </summary>
+public interface IKnowledgeRetriever
+{
+    IReadOnlyList<KnowledgeSnippet> Search(string query, int topK);
+}
+
+public sealed class KnowledgeOptions
+{
+    public const string Section = "Knowledge";
+
+    /// <summary>In-memory corpus the default lexical retriever searches.</summary>
+    public List<KnowledgeDocumentOptions> Documents { get; set; } = [];
+
+    public int DefaultTopK { get; set; } = 3;
+}
+
+public sealed class KnowledgeDocumentOptions
+{
+    public string Source { get; set; } = string.Empty;
+
+    public string Text { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Default retriever: deterministic term-overlap scoring over a configured in-memory corpus.
+/// Dependency-free so RAG works out of the box; a pgvector/embeddings retriever can replace it
+/// behind <see cref="IKnowledgeRetriever"/> without touching the agent-facing tool.
+/// </summary>
+public sealed class LexicalKnowledgeRetriever : IKnowledgeRetriever
+{
+    private static readonly char[] Separators =
+        [' ', '\t', '\n', '\r', '.', ',', ';', ':', '!', '?', '(', ')', '[', ']', '{', '}', '"', '\'', '/', '\\', '-'];
+
+    private readonly IReadOnlyList<KnowledgeDocument> _corpus;
+
+    public LexicalKnowledgeRetriever(IOptions<KnowledgeOptions> options)
+        : this((options.Value.Documents ?? []).Select(d => new KnowledgeDocument(d.Source, d.Text)))
+    {
+    }
+
+    public LexicalKnowledgeRetriever(IEnumerable<KnowledgeDocument> corpus)
+    {
+        _corpus = corpus.Where(d => !string.IsNullOrWhiteSpace(d.Text)).ToArray();
+    }
+
+    public IReadOnlyList<KnowledgeSnippet> Search(string query, int topK)
+    {
+        var queryTerms = Tokenize(query).Distinct().ToArray();
+        if (queryTerms.Length == 0 || _corpus.Count == 0 || topK <= 0)
+        {
+            return [];
+        }
+
+        return _corpus
+            .Select(doc => new { doc, score = Score(queryTerms, Tokenize(doc.Text)) })
+            .Where(scored => scored.score > 0)
+            .OrderByDescending(scored => scored.score)
+            .Take(topK)
+            .Select(scored => new KnowledgeSnippet(scored.doc.Source, scored.doc.Text, scored.score))
+            .ToArray();
+    }
+
+    private static double Score(IReadOnlyCollection<string> queryTerms, IEnumerable<string> docTerms)
+    {
+        var docSet = new HashSet<string>(docTerms);
+        if (docSet.Count == 0)
+        {
+            return 0;
+        }
+
+        var matches = queryTerms.Count(docSet.Contains);
+        return (double)matches / queryTerms.Count; // fraction of query terms present in the doc
+    }
+
+    private static IEnumerable<string> Tokenize(string? text) =>
+        (text ?? string.Empty)
+            .ToLowerInvariant()
+            .Split(Separators, StringSplitOptions.RemoveEmptyEntries)
+            .Where(token => token.Length >= 2);
+}

src/Autofac.Agents/Tools/KnowledgeSearchTool.cs

@@ -0,0 +1,81 @@
+using System.Globalization;
+using System.Text;
+using Autofac.Agents.Knowledge;
+using Autofac.Domain.AgentRuntime;
+
+namespace Autofac.Agents.Tools;
+
+/// <summary>
+/// Policy-gated retrieval tool (#176): an agent searches the knowledge base and gets back
+/// ranked snippets with source citations, recorded like any other tool invocation. Runs
+/// through the Tool Gateway, so it is subject to the same allow/deny and policy decisions.
+/// </summary>
+public sealed class KnowledgeSearchTool : IAgentTool, IToolSchemaProvider
+{
+    private const int DefaultTopK = 3;
+    private const int MaxTopK = 10;
+
+    private readonly IKnowledgeRetriever _retriever;
+
+    public KnowledgeSearchTool(IKnowledgeRetriever retriever)
+    {
+        _retriever = retriever;
+    }
+
+    public string Name => "knowledge.search";
+
+    public string Category => AgentToolCategories.Knowledge;
+
+    public IReadOnlyList<ToolSchemaParameter> GetParameters() =>
+    [
+        new("query", "string", "The question or query to retrieve relevant context for.", Required: true),
+        new("top_k", "integer", "Maximum number of snippets to return (1-10, default 3).", Required: false),
+    ];
+
+    public void Validate(IReadOnlyDictionary<string, string> input)
+    {
+        if (!input.TryGetValue("query", out var query) || string.IsNullOrWhiteSpace(query))
+        {
+            throw new InvalidOperationException("Tool input is missing required field 'query'.");
+        }
+    }
+
+    public Task<AgentToolExecutionResult> ExecuteAsync(
+        AgentToolExecutionContext context,
+        IReadOnlyDictionary<string, string> input,
+        CancellationToken cancellationToken)
+    {
+        var query = input["query"];
+        var topK = DefaultTopK;
+        if (input.TryGetValue("top_k", out var rawTopK)
+            && int.TryParse(rawTopK, NumberStyles.Integer, CultureInfo.InvariantCulture, out var parsed))
+        {
+            topK = Math.Clamp(parsed, 1, MaxTopK);
+        }
+
+        var snippets = _retriever.Search(query, topK);
+        if (snippets.Count == 0)
+        {
+            return Task.FromResult(new AgentToolExecutionResult(
+                Succeeded: true,
+                Output: "No relevant knowledge was found.",
+                FailureReason: null));
+        }
+
+        var builder = new StringBuilder();
+        builder.AppendLine(CultureInfo.InvariantCulture, $"Found {snippets.Count} relevant snippet(s):");
+        var index = 1;
+        foreach (var snippet in snippets)
+        {
+            builder.AppendLine(CultureInfo.InvariantCulture, $"[{index}] source: {snippet.Source} (score {snippet.Score:0.00})");
+            builder.AppendLine(snippet.Text);
+            builder.AppendLine();
+            index++;
+        }
+
+        return Task.FromResult(new AgentToolExecutionResult(
+            Succeeded: true,
+            Output: builder.ToString().TrimEnd(),
+            FailureReason: null));
+    }
+}

src/Autofac.Domain/AgentRuntime/AgentRuntimeContract.cs

@@ -72,6 +72,7 @@ public static class AgentToolCategories
     public const string Integration = "integration";
     public const string Mcp = "mcp";
     public const string SubAgent = "sub-agent";
+    public const string Knowledge = "knowledge";
 }
 
 public sealed record AgentMcpServerContract

tests/Autofac.Agents.Tests/KnowledgeRetrieverTests.cs

@@ -0,0 +1,42 @@
+using Autofac.Agents.Knowledge;
+
+namespace Autofac.Agents.Tests;
+
+public sealed class KnowledgeRetrieverTests
+{
+    private static LexicalKnowledgeRetriever Retriever() => new(
+    [
+        new KnowledgeDocument("deploy.md", "How to deploy the service to production using Helm and Kubernetes."),
+        new KnowledgeDocument("auth.md", "Authentication uses OIDC JWT bearer tokens and role mapping."),
+        new KnowledgeDocument("empty.md", string.Empty),
+    ]);
+
+    [Fact]
+    public void Search_RanksRelevantDocumentHighest()
+    {
+        var results = Retriever().Search("how do I deploy with kubernetes", topK: 2);
+
+        Assert.NotEmpty(results);
+        Assert.Equal("deploy.md", results[0].Source);
+    }
+
+    [Fact]
+    public void Search_RespectsTopK()
+    {
+        var results = Retriever().Search("deploy kubernetes authentication oidc", topK: 1);
+        Assert.Single(results);
+    }
+
+    [Fact]
+    public void Search_EmptyQueryOrCorpus_ReturnsEmpty()
+    {
+        Assert.Empty(Retriever().Search(string.Empty, 3));
+        Assert.Empty(new LexicalKnowledgeRetriever(Array.Empty<KnowledgeDocument>()).Search("deploy", 3));
+    }
+
+    [Fact]
+    public void Search_IrrelevantQuery_ReturnsEmpty()
+    {
+        Assert.Empty(Retriever().Search("xylophone zebra", 3));
+    }
+}

tests/Autofac.Agents.Tests/KnowledgeSearchToolTests.cs

@@ -0,0 +1,46 @@
+using Autofac.Agents.Knowledge;
+using Autofac.Agents.Tools;
+
+namespace Autofac.Agents.Tests;
+
+public sealed class KnowledgeSearchToolTests
+{
+    private static AgentToolExecutionContext Context() =>
+        new("run", "step", "agent", "knowledge.search", null, "general", "tag", 1);
+
+    private static KnowledgeSearchTool Tool() => new(new LexicalKnowledgeRetriever(
+    [
+        new KnowledgeDocument("deploy.md", "Deploy with Helm to Kubernetes."),
+    ]));
+
+    [Fact]
+    public async Task ExecuteAsync_ReturnsSnippetsWithCitations()
+    {
+        var result = await Tool().ExecuteAsync(
+            Context(),
+            new Dictionary<string, string> { ["query"] = "deploy kubernetes" },
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        Assert.Contains("deploy.md", result.Output);
+        Assert.Contains("Deploy with Helm", result.Output!);
+    }
+
+    [Fact]
+    public void Validate_MissingQuery_Throws()
+    {
+        Assert.Throws<InvalidOperationException>(() => Tool().Validate(new Dictionary<string, string>()));
+    }
+
+    [Fact]
+    public async Task ExecuteAsync_NoMatch_ReturnsNoResultsMessage()
+    {
+        var result = await Tool().ExecuteAsync(
+            Context(),
+            new Dictionary<string, string> { ["query"] = "xylophone" },
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        Assert.Contains("No relevant knowledge", result.Output!);
+    }
+}