Глава 9. Оценка и observability

package eval

// Step — один шаг траектории агента (то, что вы и так пишете в спан трейсинга).
type Step struct {
    Tool string // вызванный инструмент ("" — обычный ответ модели)
    Args map[string]any
}

// TrajectoryCheck проверяет НАБОР СВОЙСТВ траектории, а не точный путь:
// у корректного агента много допустимых траекторий, поэтому строгое
// совпадение с эталоном хрупко. Возвращаем список нарушений (пусто = ок).
func TrajectoryCheck(steps []Step, maxSteps int) []string {
    var violations []string

    if len(steps) > maxSteps {
        violations = append(violations, "превышен бюджет шагов")
    }

    // Инвариант безопасности: необратимое действие только после подтверждения.
    confirmed := false
    seen := map[string]int{}
    for _, s := range steps {
        if s.Tool == "" {
            continue
        }
        seen[s.Tool]++
        if s.Tool == "confirm_action" {
            confirmed = true
        }
        if s.Tool == "delete_account" && !confirmed {
            violations = append(violations, "delete_account вызван без предшествующего confirm_action")
        }
    }

    // Признак топтания на месте: один и тот же инструмент с одинаковым смыслом много раз.
    for tool, n := range seen {
        if n > 3 {
            violations = append(violations, "подозрение на зацикливание: "+tool+" вызван слишком часто")
        }
    }
    return violations
}

package eval

import "math"

// wilson возвращает нижнюю и верхнюю границы доверительного интервала Уилсона
// для доли успеха (successes из n) при заданном z (z=1.96 ≈ 95%).
// Уилсон корректнее наивной нормальной формулы на малых n и у краёв (p→0/1).
func wilson(successes, n int, z float64) (lo, hi float64) {
    if n == 0 {
        return 0, 1 // нет данных — ничего не утверждаем
    }
    phat := float64(successes) / float64(n)
    z2 := z * z
    denom := 1 + z2/float64(n)
    center := phat + z2/(2*float64(n))
    margin := z * math.Sqrt(phat*(1-phat)/float64(n)+z2/(4*float64(n)*float64(n)))
    return (center - margin) / denom, (center + margin) / denom
}

// betterWithConfidence грубо отвечает: версия B лучше A или это шум?
// Если интервалы не перекрываются — разница похожа на сигнал.
func betterWithConfidence(succA, nA, succB, nB int) string {
    loA, hiA := wilson(succA, nA, 1.96)
    loB, hiB := wilson(succB, nB, 1.96)
    switch {
    case loB > hiA:
        return "B лучше A (интервалы не перекрываются)"
    case loA > hiB:
        return "A лучше B (интервалы не перекрываются)"
    default:
        return "разница в пределах шума — нужен больший датасет"
    }
}

// Case — один кейс датасета. Эталон (Want) описывает проверяемые свойства,
// а не точную строку: для агентов точное совпадение почти бесполезно.
type Case struct {
    ID     string
    Input  string
    Want   Expect // что должно быть верно в ответе
}

// Expect — программно проверяемые свойства ответа (грунт для code-based grading).
type Expect struct {
    MustContain   []string // ответ обязан содержать эти подстроки/факты
    MustNotCall   []string // эти инструменты вызывать нельзя
    MaxSteps      int      // потолок числа шагов
    JSONSchema    string   // если задана — ответ должен быть валиден по схеме
}

// Result — исход прогона одного кейса.
type Result struct {
    CaseID    string
    Passed    bool
    CodeScore float64 // программный скор 0..1
    JudgeScore float64 // скор LLM-as-judge 0..1 (если применялся)
    Steps     int
    Tokens    int
    Notes     []string
}

// RunEval прогоняет весь датасет и возвращает агрегаты. Прогон каждого кейса
// изолирован: свежее состояние агента, общий бюджет шагов из Expect.
func RunEval(ctx context.Context, ds []Case, run AgentRunner, judge Judge) (Report, error) {
    var results []Result
    for _, c := range ds {
        tr, err := run(ctx, c.Input, c.Want.MaxSteps) // вернёт ответ + трейс
        if err != nil {
            results = append(results, Result{CaseID: c.ID, Passed: false,
                Notes: []string{"runtime error: " + err.Error()}})
            continue
        }
        r := scoreCode(c, tr)              // сначала дешёвый программный скоринг
        if c.Want.JSONSchema == "" && needsJudge(c) {
            r.JudgeScore = judge.Score(ctx, c, tr.Output) // субъективные критерии
        }
        r.Passed = r.CodeScore >= 1.0 && r.JudgeScore >= judgeThreshold
        results = append(results, r)
    }
    return aggregate(results), nil // success rate, средние шаги/токены/стоимость
}

// Judge оценивает субъективные свойства ответа отдельным вызовом модели.
// Ключ к надёжности — ЯВНЫЙ rubric и калибровка на golden set.
type Judge struct {
    client *anthropic.Client
    model  anthropic.Model // судья — желательно ДРУГОГО семейства, чем оцениваемая модель
}

const rubric = `Оцени ответ агента по шкале 0..1 строго по критериям:
- Грунтинг: каждое утверждение подтверждается приведённым источником (0.4)
- Полнота: отвечает на весь вопрос пользователя (0.3)
- Формат: соблюдена требуемая структура, нет лишнего (0.3)
Верни ТОЛЬКО число от 0 до 1 с двумя знаками.`

func (j Judge) Score(ctx context.Context, c Case, answer string) float64 {
    prompt := rubric + "\n\nВопрос: " + c.Input + "\nОтвет: " + answer
    msg, err := j.client.Messages.New(ctx, anthropic.MessageNewParams{
        Model:     j.model,
        MaxTokens: 16,                  // ждём одно число — не даём судье «растекаться»
        Messages:  []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock(prompt))},
    })
    if err != nil {
        return 0 // непоставленный скор = провал, а не «тихий ноль» в плюс
    }
    return parseScore(msg) // распарсить число; при мусоре — 0
}

// Для ПАРНОГО сравнения (A против B) вызывай судью дважды со сменой порядка
// и усредняй — иначе позиционный сдвиг исказит результат.

// Span — единица трейсинга: один шаг цикла (вызов модели или инструмента).
// Имена атрибутов — по OpenTelemetry GenAI semantic conventions, чтобы трейсы
// были переносимы между вендорами наблюдаемости.
type Span struct {
    Name      string            // напр. "llm.call" или "tool.search_orders"
    Start     time.Time
    Attrs     map[string]any    // gen_ai.request.model, gen_ai.usage.input_tokens, ...
    Err       error
}

// traceStep оборачивает любой шаг агента и пишет span в трейс. Возвращает
// результат шага как есть — обёртка прозрачна для логики цикла.
func traceStep[T any](ctx context.Context, tr *Trace, name string, attrs map[string]any,
    step func(context.Context) (T, error)) (T, error) {

    s := Span{Name: name, Start: now(), Attrs: attrs}
    out, err := step(ctx)
    s.Err = err
    s.Attrs["duration_ms"] = since(s.Start).Milliseconds()
    tr.Add(s)         // span ляжет в дерево запроса; агрегаты соберём поверх трейсов
    return out, err
}

// Client — узкий интерфейс над LLM-провайдером. Прод-код зависит от него,
// а не от конкретного SDK, поэтому в тестах модель легко подменить моком.
type Client interface {
    Complete(ctx context.Context, req Request) (Response, error)
}

// mockClient — детерминированная подмена для юнит-тестов. Отдаёт заранее
// заданные ответы по очереди; никакой сети, прогон за миллисекунды.
type mockClient struct {
    responses []Response
    calls     int
}

func (m *mockClient) Complete(_ context.Context, _ Request) (Response, error) {
    if m.calls >= len(m.responses) {
        return Response{}, errors.New("mock: запрошено больше ответов, чем задано")
    }
    r := m.responses[m.calls]
    m.calls++
    return r, nil
}

// Теперь управляющую логику цикла можно проверять детерминированно: подаём
// фиксированный tool-call в первом ответе и финальный текст во втором.
func TestLoop_RunsToolThenFinishes(t *testing.T) {
    mc := &mockClient{responses: []Response{
        {ToolCalls: []ToolCall{{Name: "search", Args: map[string]any{"q": "x"}}}},
        {Text: "готово"},
    }}
    agent := NewAgent(mc, testTools())
    out, err := agent.Run(context.Background(), "найди x", 5)
    if err != nil {
        t.Fatalf("неожиданная ошибка: %v", err)
    }
    if out != "готово" {
        t.Errorf("ожидали финальный текст, получили %q", out)
    }
}

// update — флаг перегенерации эталонов: go test -update перепишет .golden,
// обычный прогон только сравнивает. testdata/ игнорируется тулчейном Go.
var update = flag.Bool("update", false, "перегенерировать golden-файлы")

// assertGolden сравнивает фактический вывод с эталоном из testdata/<name>.golden.
// При -update эталон переписывается (когда вывод изменился НАМЕРЕННО).
func assertGolden(t *testing.T, name string, got []byte) {
    t.Helper()
    path := filepath.Join("testdata", name+".golden")
    if *update {
        if err := os.WriteFile(path, got, 0o644); err != nil {
            t.Fatalf("не записал golden: %v", err)
        }
        return
    }
    want, err := os.ReadFile(path)
    if err != nil {
        t.Fatalf("нет эталона (запустите go test -update): %v", err)
    }
    if !bytes.Equal(got, want) {
        t.Errorf("вывод разошёлся с %s.golden\nполучено: %s", name, got)
    }
}

// Записать РЕАЛЬНЫЙ ответ для эталона один раз можно через httptest: поднять
// фейковый сервер провайдера, сохранить тело ответа в testdata/*.golden,
// дальше тесты воспроизводят его из файла без сети.
func recordResponse(t *testing.T) []byte {
    srv := httptest.NewServer(http.HandlerFunc(
        func(w http.ResponseWriter, r *http.Request) {
            w.Write(fakeProviderBody) // заранее снятый/смоканный ответ провайдера
        }))
    defer srv.Close()
    resp, _ := http.Get(srv.URL)
    body, _ := io.ReadAll(resp.Body)
    return body
}

// Table-driven тест инструмента: набор случаев в таблице, один прогон на каждый.
// Чисто детерминированно — это код инструмента, а не модель.
func TestSearchTool(t *testing.T) {
    cases := []struct {
        name    string
        args    map[string]any
        want    string
        wantErr bool
    }{
        {"валидный запрос", map[string]any{"q": "order-42"}, "order-42: paid", false},
        {"пустой запрос", map[string]any{"q": ""}, "", true},
        {"нет аргумента q", map[string]any{}, "", true},
    }
    for _, c := range cases {
        t.Run(c.name, func(t *testing.T) {
            got, err := searchTool(testCtx(), c.args)
            if (err != nil) != c.wantErr {
                t.Fatalf("ошибка=%v, ожидали wantErr=%v", err, c.wantErr)
            }
            if got != c.want {
                t.Errorf("получили %q, ожидали %q", got, c.want)
            }
        })
    }
}

// Одна итерация управляющего цикла: на tool-call агент обязан вызвать инструмент
// и вернуть его результат в контекст. Модель замокана — проверяем СВОЙ код.
func TestStep_DispatchesToolCall(t *testing.T) {
    mc := &mockClient{responses: []Response{
        {ToolCalls: []ToolCall{{Name: "search", Args: map[string]any{"q": "order-42"}}}},
    }}
    st := newState(mc, testTools())
    if err := st.step(context.Background()); err != nil {
        t.Fatalf("step: %v", err)
    }
    if last := st.lastToolResult(); last != "order-42: paid" {
        t.Errorf("инструмент не вызван корректно: %q", last)
    }
}

// Пайплайн маховика улучшения: выбрать кейсы из прод-трейсов, разметить,
// пополнить eval-датасет, прогнать тот же eval-раннер и сравнить с baseline.
func RunFlywheel(ctx context.Context, traces []Trace, ds []Case, run AgentRunner, judge Judge) (Diff, error) {
    // 1) Выборка из прод-трейсов: берём провалы и нетипичные траектории —
    //    именно они дают новые регрессионные кейсы.
    candidates := sampleInteresting(traces) // напр. high steps, ошибки, низкий judge-скор

    // 2) Разметка: человек/судья фиксирует эталон (Want) для каждого кандидата.
    labeled := labelCases(ctx, candidates, judge)

    // 3) Курирование: пополняем версионируемый датасет (без дублей).
    grown := mergeDataset(ds, labeled)

    // 4) Переоценка: тот же eval-раннер из этой главы, но на расширенном наборе.
    base, err := RunEval(ctx, ds, run, judge)
    if err != nil {
        return Diff{}, err
    }
    next, err := RunEval(ctx, grown, run, judge)
    if err != nil {
        return Diff{}, err
    }

    // 5) Отчёт о регрессиях: что просело относительно baseline — это и есть
    //    гейт для выката (см. релизный процесс, Глава 13).
    return diffReports(base, next), nil
}