# Using the New Evaluation APIs

## Overview

The evaluation system now provides unified, type-safe APIs that replace the previous multiple entry points. This guide shows how to use the new features.

## Quick Start

### Unified Evaluation System

**Recommended approach** - Single entry point for all evaluation types:

```rust
use anno::eval::EvalSystem;
use anno::eval::task_mapping::Task;
use anno::StackedNER;

let model = Box::new(StackedNER::default());

let results = EvalSystem::new()
    .with_tasks(vec![Task::NER])
    .with_backends(vec!["stacked".to_string()])
    .with_bias_analysis(true)
    .with_model(model, Some("stacked".to_string()))
    .run()?;

// Access results
if let Some(standard) = &results.standard {
    println!("F1: {:.1}%", standard.f1 * 100.0);
}

if let Some(bias) = &results.bias {
    // Bias results available
}
```

### Configuration Builders

**Cleaner configuration** - Use builders instead of manual structs:

```rust
use anno::eval::config_builder::TaskEvalConfigBuilder;
use anno::eval::task_mapping::Task;

let config = TaskEvalConfigBuilder::new()
    .with_tasks(vec![Task::NER])
    .add_backend("stacked".to_string())
    .add_backend("gliner2".to_string())
    .with_max_examples(1000)
    .with_confidence_intervals(true)
    .with_familiarity(true)
    .build();
```

### Type-Safe Backend Names

**Compile-time checking** - Use enum instead of strings:

```rust
use anno::eval::BackendName;

// Compile-time checked
let backend = BackendName::GLiNER2;
let name = backend.as_str(); // "gliner2"

// Parse from string (backward compatible)
if let Some(backend) = BackendName::from_str("stacked") {
    println!("Backend: {:?}", backend);
}

// Use in EvalSystem
let results = EvalSystem::new()
    .with_backend_names(vec![BackendName::Stacked, BackendName::GLiNER2])
    .run()?;
```

## Migration Guide

### From TaskEvaluator

**Before:**
```rust
let evaluator = TaskEvaluator::new()?;
let config = TaskEvalConfig { ... };
let results = evaluator.evaluate_all(config)?;
```

**After:**
```rust
let results = EvalSystem::new()
    .with_tasks(config.tasks)
    .with_datasets(config.datasets)
    .with_backends(config.backends)
    .run()?;
```

### From EvalHarness

**Before:**
```rust
let harness = EvalHarness::new(EvalConfig::default())?;
let results = harness.run_synthetic()?;
```

**After:**
```rust
let results = EvalSystem::new()
    .with_tasks(vec![Task::NER])
    .run()?;
```

### From Manual Config Structs

**Before:**
```rust
let config = TaskEvalConfig {
    tasks: vec![Task::NER],
    datasets: vec![],
    backends: vec!["stacked".to_string()],
    max_examples: Some(100),
    seed: Some(42),
    require_cached: false,
    relation_threshold: 0.5,
    robustness: false,
    compute_familiarity: true,
    temporal_stratification: false,
    confidence_intervals: true,
};
```

**After:**
```rust
let config = TaskEvalConfigBuilder::new()
    .with_tasks(vec![Task::NER])
    .add_backend("stacked".to_string())
    .with_max_examples(100)
    .with_seed(42)
    .with_confidence_intervals(true)
    .with_familiarity(true)
    .build();
```

### From String Backend Names

**Before:**
```rust
let backend = "gliner2"; // Typo-prone!
```

**After:**
```rust
use anno::eval::BackendName;
let backend = BackendName::GLiNER2; // Compile-time checked!
```

## Examples

See these examples for complete usage:

- `examples/unified_evaluation.rs` - Unified EvalSystem usage
- `examples/config_builder_usage.rs` - Configuration builders
- `examples/migrating_to_unified.rs` - Migration patterns
- `examples/task_evaluation.rs` - Updated to show both old and new APIs

## Benefits

1. **Single Entry Point**: One API for all evaluation types
2. **Type Safety**: Compile-time checking for backend names
3. **Better UX**: Builder pattern is self-documenting
4. **Composability**: Easy to combine evaluation types
5. **Unified Results**: Consistent result structure

## Backward Compatibility

All old APIs still work! The new APIs are additions, not replacements. You can migrate gradually:

- `TaskEvaluator` - Still works
- `EvalHarness` - Still works
- String backend names - Still work (but consider migrating to `BackendName`)

## See Also

- `docs/UNIFIED_EVAL_SYSTEM.md` - Detailed unified system guide
- `docs/EVAL_FLOW_QUICK_REFERENCE.md` - Quick reference
- `docs/EVAL_IMPROVEMENTS_COMPLETE.md` - All improvements

