query_id,query,expected_uids,priority,notes,added_at
q-0001,"macbook screen flicker","uid-1; uid-2; uid-3",p1,"flagship product",2026-01-15
q-0002,"battery drain overnight","uid-9; uid-12",p2,"known acronym BD",2026-01-15
q-0003,"error 0x80004005","uid-44",p1,"exact identifier",2026-01-15

// Endpoint: evaluation/import-golden-set
// Body: the raw CSV (same shape as the table above).
var csv   = Body;
var lines = csv.Split('\n').Skip(1).Where(l => !string.IsNullOrWhiteSpace(l));
int count = 0;

foreach (var line in lines)
{
    var cols          = line.Split(',');
    var queryId       = cols[0].Trim().Trim('"');
    var queryText     = cols[1].Trim().Trim('"');
    var expectedUids  = cols[2].Trim().Trim('"')
                            .Split(';', StringSplitOptions.RemoveEmptyEntries)
                            .Select(u => u.Trim())
                            .ToList();
    var priority      = cols[3].Trim().Trim('"');
    var notes         = cols.Length > 4 ? cols[4].Trim().Trim('"') : "";

    var query = await Graph.GetOrAddLockedAsync(N.GoldenQuery.Type, queryId);
    try
    {
        query.SetString(N.GoldenQuery.QueryText,    queryText);
        query.SetString(N.GoldenQuery.Priority,     priority);
        query.SetString(N.GoldenQuery.Notes,        notes);
        query.SetStringList(N.GoldenQuery.ExpectedUids, expectedUids);
        query.SetTime  (N.GoldenQuery.AddedAt,      Time.Now);

        foreach (var uid in expectedUids)
        {
            var target     = UID128.Parse(uid);
            var targetType = Graph.GetNodeTypeUIDForUID(target);
            query.AddUniqueEdge(E.Expects, target, targetType);
        }

        await Graph.CommitAsync(query);
        count++;
    }
    catch
    {
        Graph.AbandonChanges(query);
        throw;
    }
}

return Ok($"Imported {count} golden queries");

// Endpoint: evaluation/metrics
// Shared metric helpers. Imported by evaluation/score-query and any other
// endpoint that needs to compute Precision@k / NDCG@k against a label set.
public static class Metrics
{
    public static double PrecisionAtK(IReadOnlyList<UID128> retrieved, ISet<UID128> expected, int k)
    {
        if (k <= 0 || retrieved.Count == 0) return 0;
        var hits = retrieved.Take(k).Count(expected.Contains);
        return hits / (double)k;
    }

    public static double ReciprocalRank(IReadOnlyList<UID128> retrieved, ISet<UID128> expected)
    {
        for (int i = 0; i < retrieved.Count; i++)
            if (expected.Contains(retrieved[i])) return 1.0 / (i + 1);
        return 0.0;
    }

    public static double DcgAtK(IReadOnlyList<UID128> retrieved, ISet<UID128> expected, int k)
    {
        double sum = 0;
        var cap = Math.Min(k, retrieved.Count);
        for (int i = 0; i < cap; i++)
            if (expected.Contains(retrieved[i]))
                sum += 1.0 / Math.Log2(i + 2);
        return sum;
    }

    public static double NdcgAtK(IReadOnlyList<UID128> retrieved, IReadOnlyList<UID128> expectedRanked, int k)
    {
        var expectedSet = new HashSet<UID128>(expectedRanked);
        var ideal       = DcgAtK(expectedRanked, expectedSet, k);
        return ideal == 0 ? 0 : DcgAtK(retrieved, expectedSet, k) / ideal;
    }

    public static double RecallAtK(IReadOnlyList<UID128> retrieved, ISet<UID128> expected, int k)
        => retrieved.Take(k).Any(expected.Contains) ? 1.0 : 0.0;
}

// Endpoint: evaluation/run-search
// Returns the top-50 UIDs for a single query. Read-only.
public class RunSearchRequest  { public string Query;   public double? Alpha; }
public class RunSearchResponse { public List<UID128> RetrievedUids; }

var req = Body.FromJson<RunSearchRequest>();

var uids = Q()
    .StartSearch(N.SupportCase.Type, N.SupportCase.Body, SearchExpression.Parse(req.Query))
    .Take(50)
    .ToUIDList();

return new RunSearchResponse { RetrievedUids = uids };

// Endpoint: evaluation/score-query
//ImportEndpoint("evaluation/metrics")

public class ScoreQueryRequest  { public string QueryId; public double? Alpha; }
public class ScoreQueryResponse
{
    public string  QueryId;
    public double  PrecisionAt1, PrecisionAt3, NdcgAt10, RecallAt50;
    public bool    Zero;
}

var req = Body.FromJson<ScoreQueryRequest>();

var goldenNode = Q().StartAt(N.GoldenQuery.Type, req.QueryId).AsEnumerable().FirstOrDefault();
if (goldenNode is null) return NotFound($"GoldenQuery '{req.QueryId}' not in graph");

var queryText    = goldenNode.GetString(N.GoldenQuery.QueryText);
var expectedList = goldenNode.GetStringList(N.GoldenQuery.ExpectedUids)
                            .Select(UID128.Parse)
                            .ToList();
var expectedSet  = new HashSet<UID128>(expectedList);

var search = await RunEndpointAsync<RunSearchResponse>(
    "evaluation/run-search",
    new RunSearchRequest { Query = queryText, Alpha = req.Alpha });

var retrieved = search.RetrievedUids;

return new ScoreQueryResponse
{
    QueryId      = req.QueryId,
    PrecisionAt1 = Metrics.PrecisionAtK(retrieved, expectedSet, 1),
    PrecisionAt3 = Metrics.PrecisionAtK(retrieved, expectedSet, 3),
    NdcgAt10     = Metrics.NdcgAtK   (retrieved, expectedList, 10),
    RecallAt50   = Metrics.RecallAtK (retrieved, expectedSet, 50),
    Zero         = retrieved.Count == 0,
};

// Endpoint: evaluation/run-suite (Pooling, Read Only)
public class RunSuiteRequest  { public double? Alpha; }
public class RunSuiteResponse
{
    public double PrecisionAt1, PrecisionAt3, NdcgAt10, RecallAt50, ZeroResult;
    public List<ScoreQueryResponse> PerQuery;
}

var req     = Body.FromJson<RunSuiteRequest>() ?? new RunSuiteRequest();
var queries = Q().StartAt(N.GoldenQuery.Type).ToList();
var scored  = new List<ScoreQueryResponse>(queries.Count);

for (int i = 0; i < queries.Count; i++)
{
    var qid    = queries[i].GetString(N.GoldenQuery.QueryId);
    var result = await RunEndpointAsync<ScoreQueryResponse>(
        "evaluation/score-query",
        new ScoreQueryRequest { QueryId = qid, Alpha = req.Alpha });

    scored.Add(result);
    await RelayStatusAsync($"Scored {qid} ({i + 1}/{queries.Count})");
}

double Mean(Func<ScoreQueryResponse, double> f) => scored.Count == 0 ? 0 : scored.Average(f);

return new RunSuiteResponse
{
    PrecisionAt1 = Math.Round(Mean(r => r.PrecisionAt1), 3),
    PrecisionAt3 = Math.Round(Mean(r => r.PrecisionAt3), 3),
    NdcgAt10     = Math.Round(Mean(r => r.NdcgAt10),     3),
    RecallAt50   = Math.Round(Mean(r => r.RecallAt50),   3),
    ZeroResult   = Math.Round(scored.Count(r => r.Zero) / (double)Math.Max(scored.Count, 1), 3),
    PerQuery     = scored,
};

// Endpoint: evaluation/per-query-diff
public class DiffRequest
{
    public List<ScoreQueryResponse> Baseline;
    public List<ScoreQueryResponse> Candidate;
}

var req     = Body.FromJson<DiffRequest>();
var byId    = req.Candidate.ToDictionary(c => c.QueryId);
var alerts  = new List<object>();

foreach (var b in req.Baseline)
{
    if (!byId.TryGetValue(b.QueryId, out var c)) continue;

    var droppedToZero = b.PrecisionAt3 == 1.0 && c.PrecisionAt3 == 0.0;
    var bigNdcgDrop   = (b.NdcgAt10 - c.NdcgAt10) > 0.5;

    if (droppedToZero || bigNdcgDrop)
    {
        alerts.Add(new
        {
            b.QueryId,
            DeltaPrecisionAt3 = c.PrecisionAt3 - b.PrecisionAt3,
            DeltaNdcgAt10     = c.NdcgAt10     - b.NdcgAt10,
            DroppedToZero     = droppedToZero,
        });
    }
}

return alerts;

// Endpoint: evaluation/sweep-alpha (Pooling, Read Only)
var alphas = new[] { 0.0, 0.25, 0.5, 0.75, 1.0 };
var rows   = new List<object>();

foreach (var alpha in alphas)
{
    await RelayStatusAsync($"Running suite at α = {alpha}");
    var suite = await RunEndpointAsync<RunSuiteResponse>(
        "evaluation/run-suite",
        new { Alpha = alpha });

    rows.Add(new
    {
        Alpha        = alpha,
        PrecisionAt3 = suite.PrecisionAt3,
        NdcgAt10     = suite.NdcgAt10,
        RecallAt50   = suite.RecallAt50,
    });
}

return rows;