@FunctionalInterface
public interface LLMJudge {
    String judge(String prompt);
}

// Plug in any LLM client
LLMJudge judge = prompt -> myLlmClient.chat(prompt);

public interface Evaluator {
    String name();
    EvaluationResult evaluate(EvaluationInput context);
}

Evaluator.EvaluationInput input = Evaluator.EvaluationInput.builder()
    .userInput("What causes tides?")
    .agentResponse("Tides are caused by gravitational pull of the Moon.")
    .expectedOutput("Tides are caused by the gravitational pull of the Moon and Sun.")
    .metadata("retrieved_documents", List.of(doc1, doc2))
    .build();

public record EvaluationResult(
    String evaluatorName,
    double score,
    String details,
    Map<String, Double> metrics,
    Instant timestamp
) {
    // Factory methods
    static EvaluationResult of(String name, double score, String details, Map<String, Double> metrics);
    static EvaluationResult pass(String name, String details);   // score = 1.0
    static EvaluationResult fail(String name, String details);   // score = 0.0

    boolean passed(double threshold);
}

var evaluator = new FaithfulnessEvaluator(judge);
var input = Evaluator.EvaluationInput.builder()
    .agentResponse("Paris is the capital of France and has 2.1 million people.")
    .metadata("retrieved_documents", List.of(
        "Paris is the capital and most populous city of France.",
        "The population of Paris is approximately 2.1 million."
    ))
    .build();

EvaluationResult result = evaluator.evaluate(input);
// result.score() -> 1.0 (both claims supported)
// result.metrics(): supported_claims, total_claims, hallucinated_claims

var evaluator = new ContextualPrecisionEvaluator(judge);
var input = Evaluator.EvaluationInput.builder()
    .userInput("What causes tides?")
    .expectedOutput("Gravitational pull of the Moon and Sun causes tides.")
    .metadata("retrieved_documents", List.of(
        "Tides are caused by gravitational forces of the Moon and Sun.",
        "The Pacific Ocean is the largest ocean on Earth.",
        "Spring tides occur when the Moon and Sun are aligned."
    ))
    .build();

EvaluationResult result = evaluator.evaluate(input);
// result.metrics(): relevant_docs, total_docs, naive_precision

var evaluator = new ContextualRecallEvaluator(judge);
var input = Evaluator.EvaluationInput.builder()
    .expectedOutput("Tides are caused by the Moon's gravity. Spring tides happen during full and new moons.")
    .metadata("retrieved_documents", List.of(
        "The Moon's gravitational pull is the primary cause of ocean tides."
        // Missing: spring tide information -> recall will be less than 1.0
    ))
    .build();

EvaluationResult result = evaluator.evaluate(input);
// result.metrics(): attributed_facts, total_facts, missing_facts

var evaluator = new AnswerRelevancyEvaluator(judge);
var input = Evaluator.EvaluationInput.builder()
    .userInput("What is the boiling point of water?")
    .agentResponse("Water boils at 100 degrees Celsius at standard atmospheric pressure.")
    .build();

EvaluationResult result = evaluator.evaluate(input);
// result.metrics(): directness, completeness, focus
// result.details() -> "directness=5/5 completeness=5/5 focus=5/5 score=1.00"

LLMJudge judge = prompt -> llmClient.chat(prompt);

var evaluators = List.of(
    new FaithfulnessEvaluator(judge),
    new ContextualPrecisionEvaluator(judge),
    new ContextualRecallEvaluator(judge),
    new AnswerRelevancyEvaluator(judge)
);

BenchmarkRunner runner = BenchmarkRunner.builder()
    .evaluators(evaluators)
    .agentFunction(testCase -> ragAgent.query(testCase.getInput()))
    .build();

var evaluator = new KnowledgeRetentionEvaluator(judge);
var input = Evaluator.EvaluationInput.builder()
    .metadata("conversation_history", List.of(
        Map.of("role", "user", "content", "My name is Alice and I work at Acme Corp."),
        Map.of("role", "assistant", "content", "Nice to meet you, Alice! How can I help?"),
        Map.of("role", "user", "content", "Can you summarize what you know about me?"),
        Map.of("role", "assistant", "content", "You're Alice and you work at Acme Corp.")
    ))
    .build();

EvaluationResult result = evaluator.evaluate(input);
// result.metrics(): retained_facts, total_facts, forgotten_facts

var evaluator = new ConversationCompletenessEvaluator(judge);
var input = Evaluator.EvaluationInput.builder()
    .metadata("conversation_goal", "Help the user book a flight to Paris")
    .metadata("conversation_history", List.of(
        Map.of("role", "user", "content", "I need to fly to Paris next week"),
        Map.of("role", "assistant", "content", "I found flights on Tuesday and Thursday. Which do you prefer?"),
        Map.of("role", "user", "content", "Tuesday please"),
        Map.of("role", "assistant", "content", "Booked! Your flight departs Tuesday at 10am. Confirmation: ABC123.")
    ))
    .build();

EvaluationResult result = evaluator.evaluate(input);
// result.metrics(): raw_score, normalized_score
// result.details() -> "completeness=5/5 score=1.00"

var evaluator = new TurnRelevancyEvaluator(judge);
var input = Evaluator.EvaluationInput.builder()
    .metadata("conversation_history", List.of(
        Map.of("role", "user", "content", "Tell me about quantum computing"),
        Map.of("role", "assistant", "content", "Quantum computing uses qubits..."),
        Map.of("role", "user", "content", "How does that compare to classical computing?"),
        Map.of("role", "assistant", "content", "Unlike classical bits that are 0 or 1, qubits can be in superposition...")
    ))
    .build();

EvaluationResult result = evaluator.evaluate(input);
// result.metrics(): context_alignment, query_addressing, coherence
// result.details() -> "context_alignment=5/5 query_addressing=5/5 coherence=5/5 score=1.00"

var evaluator = new ToxicityEvaluator(judge);
var input = Evaluator.EvaluationInput.builder()
    .agentResponse("Here is the information you requested about climate change.")
    .build();

EvaluationResult result = evaluator.evaluate(input);
// result.score() -> ~1.0 (clean)
// result.metrics(): raw_toxicity_score, insult, threat, obscenity, hate_speech, harassment

var evaluator = new BiasEvaluator(judge);
var input = Evaluator.EvaluationInput.builder()
    .userInput("What are common career paths?")
    .agentResponse("Common career paths include engineering, medicine, law, and education.")
    .build();

EvaluationResult result = evaluator.evaluate(input);
// result.metrics(): raw_bias_score, gender_bias, race_bias, age_bias, religion_bias, political_bias, socioeconomic_bias

var evaluator = new HallucinationEvaluator(judge);
var input = Evaluator.EvaluationInput.builder()
    .agentResponse("The product costs $99 and ships in 2 days.")
    .metadata("context", "Product price: $99. Shipping: 5-7 business days.")
    .build();

EvaluationResult result = evaluator.evaluate(input);
// "2 days" contradicts "5-7 business days" -> score < 1.0
// result.metrics(): supported, contradicted, fabricated, total_claims

var input = Evaluator.EvaluationInput.builder()
    .agentResponse("The study by Smith et al. (2024) in Nature found that...")
    .build();

// Checks for invented citations, self-contradictions, fabricated claims

var safetyEvaluators = List.of(
    new ToxicityEvaluator(judge),
    new BiasEvaluator(judge),
    new HallucinationEvaluator(judge)
);

double safetyThreshold = 0.8;
for (Evaluator eval : safetyEvaluators) {
    EvaluationResult result = eval.evaluate(input);
    if (!result.passed(safetyThreshold)) {
        log.warn("Safety check failed: {} scored {}", eval.name(), result.score());
    }
}

AgentTrace ──> TraceToEvalAdapter ──> EvaluationInput
                                          │
                                     Evaluator[] ──> EvaluationResult[]
                                          │
                               EvalSpanAnnotator ──> Score on trace
                                          │
                               onFailure callback ──> AutoHarness / alerting

public final class TraceEvalBridge {

    // Process a completed trace through all evaluators
    public List<EvaluationResult> process(AgentTrace trace);

    // Builder pattern
    public static Builder builder();

    // Failed evaluation record for downstream processing
    public record FailedEvaluation(
        String traceId,
        String agentId,
        String evaluatorName,
        double score,
        String details,
        Evaluator.EvaluationInput input
    ) {}
}

var bridge = TraceEvalBridge.builder()
    .evaluator(new FaithfulnessEvaluator(judge))
    .evaluator(new ToxicityEvaluator(judge))
    .evaluator(new HallucinationEvaluator(judge))
    .failureThreshold(0.5)
    .onFailure(failure -> {
        log.warn("Low score on trace {}: {} = {}",
            failure.traceId(), failure.evaluatorName(), failure.score());
        alertingService.notify(failure);
    })
    .build();

// Process a completed trace
List<EvaluationResult> results = bridge.process(completedTrace);

public final class TraceToEvalAdapter {
    public Evaluator.EvaluationInput adapt(AgentTrace trace);
}

public final class EvalSpanAnnotator {
    public void annotate(AgentTrace trace, List<EvaluationResult> results);
}

// Internally calls:
trace.addScore(Score.numeric("eval.faithfulness", 0.95, ScoreSource.HEURISTIC));
trace.addScore(Score.numeric("eval.toxicity", 1.0, ScoreSource.HEURISTIC));

// Set up once
LLMJudge judge = prompt -> evaluationLlm.chat(prompt);

var bridge = TraceEvalBridge.builder()
    .evaluator(new FaithfulnessEvaluator(judge))
    .evaluator(new ContextualRecallEvaluator(judge))
    .evaluator(new ToxicityEvaluator(judge))
    .evaluator(new BiasEvaluator(judge))
    .evaluator(new HallucinationEvaluator(judge))
    .failureThreshold(0.6)
    .onFailure(failure -> autoHarness.recordFailure(failure))
    .build();

// On every completed trace
agent.setTraceCompletionHook(trace -> {
    List<EvaluationResult> results = bridge.process(trace);
    // Scores are now on the trace for dashboards
    // Failures trigger auto-harness test generation
});

public interface EvalHook {
    // Agent lifecycle
    default void onAgentStart(EvalContext ctx, String agentId, String sessionId) {}
    default void onAgentStop(EvalContext ctx, String reason) {}
    default void onError(EvalContext ctx, Throwable error, String phase) {}

    // Chat lifecycle
    default void onBeforeChat(EvalContext ctx, String message) {}
    default void onAfterChat(EvalContext ctx, String response, long latencyMs) {}

    // Tool lifecycle
    default void onBeforeToolCall(EvalContext ctx, String toolName, Map<String, Object> arguments) {}
    default void onAfterToolCall(EvalContext ctx, String toolName, Object result,
                                  boolean success, long latencyMs) {}

    // Goal tracking
    default void onGoalCompleted(EvalContext ctx, String goalId, boolean success,
                                  Map<String, Object> details) {}

    // Memory access
    default void onMemoryAccess(EvalContext ctx, String operation, String key,
                                 int resultCount, long latencyMs) {}

    // Inter-agent communication
    default void onAgentCommunication(EvalContext ctx, String fromAgent, String toAgent,
                                       String messageType, long latencyMs) {}

    // Planning events
    default void onPlanGenerated(EvalContext ctx, String goalId,
                                  List<PlanStep> steps, long latencyMs) {}
    default void onPlanStepExecuted(EvalContext ctx, String actionName,
                                     boolean success, long latencyMs) {}
    default void onPlanCompleted(EvalContext ctx, boolean success,
                                  int totalSteps, int executedSteps, long totalLatencyMs) {}
    default void onPlanFailed(EvalContext ctx, String goalId, String reason) {}
}

onAgentStart()
    |
onBeforeChat() ----+
    |               | (loop)
onBeforeToolCall()  |
    |               |
onAfterToolCall()   |
    |               |
onAfterChat() <----+
    |
onPlanGenerated()
    |
onPlanStepExecuted() --+
    |                   | (loop)
onPlanCompleted() <----+
    |
onGoalCompleted()
    |
onAgentStop()

EvalHookManager manager = new EvalHookManager();
manager.addHook(new LatencyHook());
manager.addHook(new QualityHook());

EvalContext ctx = EvalContext.create("session-1", "agent-1");
manager.fireOnAgentStart(ctx, "agent-1", "session-1");
manager.fireOnBeforeChat(ctx, "Hello");
// ... agent execution ...
manager.fireOnAfterChat(ctx, "Hi there!", 150);
manager.fireOnAgentStop(ctx, "COMPLETED");

// Factory discovery (handled internally by Agent)
EvalHandle.Factory factory = EvalHandle.Factory.discover();
EvalHandle handle = (factory != null) ? factory.create() : EvalHandle.NOOP;

EvalContext ctx = EvalContext.create("session-123", "research-agent");

// Record metrics
ctx.recordMetric("latency", 150);
ctx.recordMetric("accuracy", 0.95);
ctx.recordMetric("latency", 200, Map.of("phase", "toolcall"));
ctx.incrementCounter("tool_calls");
ctx.incrementCounter("tokens", 1500);

// Metadata
ctx.setSpec("model", "claude-sonnet-4-20250514");
ctx.getSpec("model"); // -> "claude-sonnet-4-20250514"

// Statistics
EvalContext.MetricStats stats = ctx.getStats("latency");
// stats.count(), stats.min(), stats.max(), stats.average()
// stats.p50(), stats.p90(), stats.p99()

// Real-time streaming
ctx.addListener(event ->
    System.out.println(event.name() + " = " + event.value()));

// Export
Map<String, Object> report = ctx.toMap();
ctx.complete("SUCCESS");