Evaluation revamp docs

src/lib/navigation.ts

@@ -310,21 +310,52 @@ export const tabNavigation: NavTab[] = [
             title: 'Concepts',
             items: [
               { title: 'Understanding Evaluation', href: '/docs/evaluation/concepts/understanding-evaluation' },
-              { title: 'Eval Types', href: '/docs/evaluation/concepts/eval-types' },
-              { title: 'Eval Templates', href: '/docs/evaluation/concepts/eval-templates' },
-              { title: 'Judge Models', href: '/docs/evaluation/concepts/judge-models' },
-              { title: 'Eval Results', href: '/docs/evaluation/concepts/eval-results' },
+              { title: 'Eval types', href: '/docs/evaluation/concepts/eval-types' },
+              { title: 'Eval templates & versions', href: '/docs/evaluation/concepts/eval-templates' },
+              { title: 'Evaluator models', href: '/docs/evaluation/concepts/evaluator-models' },
+              { title: 'Output types', href: '/docs/evaluation/concepts/output-types' },
+              { title: 'Error localization', href: '/docs/evaluation/concepts/error-localization' },
+              { title: 'Guardrails', href: '/docs/evaluation/concepts/guardrails' },
+              { title: 'Composite evals', href: '/docs/evaluation/concepts/composite-evals' },
+              { title: 'Feedback', href: '/docs/evaluation/concepts/feedback' },
+              { title: 'Ground truth', href: '/docs/evaluation/concepts/ground-truth' },
             ]
           },
           {
-            title: 'Features',
+            title: 'Guides',
+            items: [
+              { title: 'Running Evaluations', href: '/docs/evaluation/guides/running-evaluations' },
+              {
+                title: 'Explore playground',
+                items: [
+                  { title: 'Overview', href: '/docs/evaluation/guides/explore-playground' },
+                  { title: 'Test an eval', href: '/docs/evaluation/guides/explore-playground/test-an-eval' },
+                  { title: 'Usage & analytics', href: '/docs/evaluation/guides/explore-playground/usage-analytics' },
+                  { title: 'Eval logs', href: '/docs/evaluation/guides/explore-playground/eval-logs' },
+                ]
+              },
+              { title: 'Create a custom eval', href: '/docs/evaluation/guides/custom-evals' },
+              { title: 'Build a composite evals', href: '/docs/evaluation/guides/composite-evals' },
+              { title: 'Set up guardrails', href: '/docs/evaluation/guides/guardrails' },
+              { title: 'Add ground truth', href: '/docs/evaluation/guides/ground-truth' },
+              { title: 'Collect feedback', href: '/docs/evaluation/guides/feedback' },
+              { title: 'Using Connectors', href: '/docs/evaluation/guides/using-connectors' },
+              { title: 'Use custom models', href: '/docs/evaluation/guides/custom-models' },
+              { title: 'Evaluate in CI/CD', href: '/docs/evaluation/guides/cicd' },
+            ]
+          },
+          {
+            title: 'References',
+            items: [
+              { title: 'Built-in evals', href: '/docs/evaluation/builtin' },
+              { title: 'Output types & scoring', href: '/docs/evaluation/reference/output-types' },
+              { title: 'SDK & API', href: '/docs/evaluation/reference/sdk-api' },
+            ]
+          },
+          {
+            title: 'Troubleshooting',
             items: [
-              { title: 'Built-in Evals', href: '/docs/evaluation/builtin' },
-              { title: 'Evaluate via Platform & SDK', href: '/docs/evaluation/features/evaluate' },
-              { title: 'Create Custom Evals', href: '/docs/evaluation/features/custom' },
-              { title: 'Use Custom Models', href: '/docs/evaluation/features/custom-models' },
-              { title: 'Future AGI Models', href: '/docs/evaluation/features/futureagi-models' },
-              { title: 'Evaluate CI/CD Pipeline', href: '/docs/evaluation/features/cicd' },
+              { title: 'Evaluation FAQ & fixes', href: '/docs/evaluation/troubleshooting' },
             ]
           },
         ]

src/lib/redirects.ts

@@ -173,12 +173,12 @@ export const redirectMap: Record<string, string> = {
   '/future-agi/get-started/evaluation/builtin-evals/toxicity': '/docs/evaluation/builtin/toxicity',
   '/future-agi/get-started/evaluation/builtin-evals/translation-accuracy': '/docs/evaluation/builtin/translation-accuracy',
   '/future-agi/get-started/evaluation/builtin-evals/valid-links': '/docs/evaluation/builtin',
-  '/future-agi/get-started/evaluation/create-custom-evals': '/docs/evaluation/features/custom',
-  '/future-agi/get-started/evaluation/evaluate-ci-cd-pipeline': '/docs/evaluation/features/cicd',
-  '/future-agi/get-started/evaluation/evaluate-patterns': '/docs/evaluation/features/evaluate',
-  '/future-agi/get-started/evaluation/future-agi-models': '/docs/evaluation/features/futureagi-models',
-  '/future-agi/get-started/evaluation/running-your-first-eval': '/docs/evaluation/features/evaluate',
-  '/future-agi/get-started/evaluation/use-custom-models': '/docs/evaluation/features/custom-models',
+  '/future-agi/get-started/evaluation/create-custom-evals': '/docs/evaluation/guides/custom-evals',
+  '/future-agi/get-started/evaluation/evaluate-ci-cd-pipeline': '/docs/evaluation/guides/cicd',
+  '/future-agi/get-started/evaluation/evaluate-patterns': '/docs/evaluation/guides/running-evaluations',
+  '/future-agi/get-started/evaluation/future-agi-models': '/docs/evaluation/concepts/evaluator-models',
+  '/future-agi/get-started/evaluation/running-your-first-eval': '/docs/evaluation/guides/running-evaluations',
+  '/future-agi/get-started/evaluation/use-custom-models': '/docs/evaluation/guides/custom-models',
   '/future-agi/get-started/knowledge-base/concept': '/docs/knowledge-base/concepts/concept',
   '/future-agi/get-started/knowledge-base/how-to/create-kb-using-sdk': '/docs/knowledge-base/features/sdk',
   '/future-agi/get-started/knowledge-base/how-to/create-kb-using-ui': '/docs/knowledge-base/features/ui',

src/pages/docs/cookbook/decrease-hallucination.mdx

@@ -592,7 +592,7 @@ The winner configuration was CharacterTextSplitter_mmr_map_rerank, which combine
 
 - **Can I create custom evaluations tailored to my RAG use case in Future AGI?**
 
-    Yes. The Deterministic Eval template in Future AGI supports custom evaluations (***Click [here](/docs/evaluation/features/custom) to learn more about deterministic eval***). This lets you apply stringent criteria to your RAG outputs minimising variability.
+    Yes. The Deterministic Eval template in Future AGI supports custom evaluations (***Click [here](/docs/evaluation/guides/custom-evals) to learn more about deterministic eval***). This lets you apply stringent criteria to your RAG outputs minimising variability.
 
 
 ## Ready to Reduce Hallucinations in Your RAG Applications?

src/pages/docs/cookbook/evaluation/eval-correction-loop.mdx

@@ -250,10 +250,10 @@ You ran a built-in eval, found rows where it disagreed with human judgment, enco
 ## Explore further
 
 <CardGroup cols={3}>
-  <Card title="Create Custom Evals" icon="wand-magic-sparkles" href="/docs/evaluation/features/custom">
+  <Card title="Create Custom Evals" icon="wand-magic-sparkles" href="/docs/evaluation/guides/custom-evals">
     Full reference for the custom eval template API
   </Card>
-  <Card title="Future AGI Models" icon="brain" href="/docs/evaluation/features/futureagi-models">
+  <Card title="Judge models" icon="brain" href="/docs/evaluation/concepts/evaluator-models">
     Pick the right judge model: turing_small, turing_flash, turing_large
   </Card>
   <Card title="Eval Templates" icon="layer-group" href="/docs/evaluation/concepts/eval-templates">

src/pages/docs/dataset/features/experiments.mdx

@@ -77,7 +77,7 @@ Experiment creation is a guided three-step flow: **Basic Info → Configuration
       <Tab title="Custom models" icon="gear">
         Models you've added through Custom Models show up in the model picker for prompt configurations across all experiment types.
         <Tip>
-          See [Custom Models](/docs/evaluation/features/custom-models) for how to register a custom or self-hosted model.
+          See [Custom Models](/docs/evaluation/guides/custom-models) for how to register a custom or self-hosted model.
         </Tip>
       </Tab>
     </Tabs>
@@ -90,7 +90,7 @@ Experiment creation is a guided three-step flow: **Basic Info → Configuration
 
     **Compare against baseline (optional)**: pick a column from the dataset to compare model outputs against (typically a ground-truth or existing run-prompt column). Skip it if you don't have a reference output yet; you can still run the experiment, attach evals that don't need a baseline, and add a base column later by editing the experiment.
 
-    **Add evaluations**: click **Add Evaluation** and pick from the [built-in eval](/docs/evaluation/builtin) catalog or [create a custom eval](/docs/evaluation/features/custom). Add as many as you need. Every eval runs on every configuration so the results are directly comparable.
+    **Add evaluations**: click **Add Evaluation** and pick from the [built-in eval](/docs/evaluation/builtin) catalog or [create a custom eval](/docs/evaluation/guides/custom-evals). Add as many as you need. Every eval runs on every configuration so the results are directly comparable.
     ![Choosing Evals](/screenshot/product/dataset/how-to/experiments-in-dataset/7.png)
 
     For each eval, map its inputs (e.g. `output`, `input`, `expected`) to the model output or to dataset columns. Mapping is required before the experiment can run.

src/pages/docs/dataset/features/run-prompt.mdx

@@ -36,28 +36,28 @@ Run Prompt lets you add a new column to your dataset that is filled by a model (
         Choose **LLM** for text generation (chat). Use for Q&A, summarization, or any text-in, text-out task. Select a chat model from the list; ensure the provider has an API key configured.
         ![LLM](/screenshot/product/dataset/how-to/run-prompt-in-dataset/3.png)
         <Tip>
-          Click [here](/docs/evaluation/features/custom-models) to learn how to create custom models.
+          Click [here](/docs/evaluation/guides/custom-models) to learn how to create custom models.
         </Tip>
       </Tab>
       <Tab title="Text-to-Speech (TTS)" icon="microphone">
         Choose **Text-to-Speech** to generate audio from text. The prompt output column will store audio (e.g. URLs). You can configure voice and format for supported TTS models.
         ![Text-to-Speech](/screenshot/product/dataset/how-to/run-prompt-in-dataset/4.png)
         <Tip>
-          Click [here](/docs/evaluation/features/custom-models) to learn how to create custom models.
+          Click [here](/docs/evaluation/guides/custom-models) to learn how to create custom models.
         </Tip>
       </Tab>
       <Tab title="Speech-to-Text (STT)" icon="page">
         Choose **Speech-to-Text** to transcribe audio into text. Use when a column contains audio; the model output will be text in the new column.
         ![Speech-to-Text](/screenshot/product/dataset/how-to/run-prompt-in-dataset/5.png)
         <Tip>
-          Click [here](/docs/evaluation/features/custom-models) to learn how to create custom models.
+          Click [here](/docs/evaluation/guides/custom-models) to learn how to create custom models.
         </Tip>
       </Tab>
       <Tab title="Image Generation" icon="image">
         Choose **Image Generation** to create images from text (or image + text) prompts. The prompt output column will store image URLs. Select an image-generation model and ensure the provider has an API key configured.
         ![Image Generation](/screenshot/product/dataset/how-to/run-prompt-in-dataset/6.png)
         <Tip>
-          Click [here](/docs/evaluation/features/custom-models) to learn how to create custom models.
+          Click [here](/docs/evaluation/guides/custom-models) to learn how to create custom models.
         </Tip>
       </Tab>
     </Tabs>

src/pages/docs/evaluation/concepts/composite-evals.mdx

@@ -0,0 +1,109 @@
+---
+title: "Composite evals"
+description: "Roll several eval child templates into one score"
+---
+
+## What are they
+
+A **composite eval** rolls several child [templates](/docs/evaluation/concepts/eval-templates) into a single score, so one check can stand for several at once. Every template is either `single` or `composite`. A composite template holds an ordered list of child templates. When it runs, the parent scores each child on the same input, then combines the child scores into one parent score with an [aggregation function](#aggregation-functions).
+
+Children share one [output type](/docs/evaluation/concepts/output-types), either pass/fail, score, or choices, so their scores are comparable before they are combined. A composite made of graded children produces a graded score; one made of pass/fail children produces a pass/fail-style score.
+
+Reach for a composite when "good" is several checks at once, for example faithful *and* on-tone *and* complete. Instead of reading three separate results, you get one score that already reflects all three, and one threshold to gate on.
+
+## Aggregation functions
+
+The parent combines child scores with one of five functions. Every child score is normalized to a 0 to 1 range first, so they can be compared on the same scale.
+
+The examples below all score the same response with three graded children: Groundedness 0.9 with weight 2.0, Tone 0.7 and Completeness 0.8 with weight 1.0.
+
+### Weighted average
+
+Each child score times its weight, divided by the total weight. This is the default. Use it when some children matter more than others.
+
+<Mermaid chart={`
+%%{init: {"flowchart": {"curve": "linear"}}}%%
+flowchart TD
+    C1["Groundedness 0.9<br/>weight 2.0"] --> AGG["Weighted average"]
+    C2["Tone 0.7<br/>weight 1.0"] --> AGG
+    C3["Completeness 0.8<br/>weight 1.0"] --> AGG
+    AGG --> P["Composite score 0.825"]
+`} />
+
+On the example: (0.9 × 2.0 + 0.7 + 0.8) / 4.0 = 0.825, and one threshold on that single number gates all three checks at once.
+
+### Average
+
+The plain mean of the child scores; weights are ignored. On the example: (0.9 + 0.7 + 0.8) / 3 = 0.8.
+
+<Mermaid chart={`
+%%{init: {"flowchart": {"curve": "linear"}}}%%
+flowchart TD
+    C1["Groundedness 0.9"] --> AGG["Average"]
+    C2["Tone 0.7"] --> AGG
+    C3["Completeness 0.8"] --> AGG
+    AGG --> P["Composite score 0.8"]
+`} />
+
+### Minimum
+
+The lowest child score, a strict gate where every child has to do well. Use it when any one failure should sink the whole score. On the example: 0.7, the Tone score.
+
+<Mermaid chart={`
+%%{init: {"flowchart": {"curve": "linear"}}}%%
+flowchart TD
+    C1["Groundedness 0.9"] --> AGG["Minimum"]
+    C2["Tone 0.7"] --> AGG
+    C3["Completeness 0.8"] --> AGG
+    AGG --> P["Composite score 0.7"]
+`} />
+
+### Maximum
+
+The highest child score, when clearing the bar on any one check is enough. On the example: 0.9, the Groundedness score.
+
+<Mermaid chart={`
+%%{init: {"flowchart": {"curve": "linear"}}}%%
+flowchart TD
+    C1["Groundedness 0.9"] --> AGG["Maximum"]
+    C2["Tone 0.7"] --> AGG
+    C3["Completeness 0.8"] --> AGG
+    AGG --> P["Composite score 0.9"]
+`} />
+
+### Pass rate
+
+The fraction of children that individually meet their own pass threshold. Use it when you care how many checks passed rather than by how much. On the example, with each child's threshold at 0.8: two of the three pass, so 0.67.
+
+<Mermaid chart={`
+%%{init: {"flowchart": {"curve": "linear"}}}%%
+flowchart TD
+    C1["Groundedness 0.9 passes"] --> AGG["Pass rate"]
+    C2["Tone 0.7 fails"] --> AGG
+    C3["Completeness 0.8 passes"] --> AGG
+    AGG --> P["Composite score 0.67"]
+`} />
+
+
+## Weights and pinned versions
+
+Two settings on each child keep a composite stable as it grows.
+
+- **Weight** sets how much a child counts in a weighted average, from 0.0 to 10.0, defaulting to 1.0. A child you care about more gets a higher weight, and a child at 0.0 drops out of the weighted score
+- **Pinned version** locks a child to a specific [template version](/docs/evaluation/concepts/eval-templates), so the composite keeps scoring the same way even after that child template is edited later
+
+Weights only change the weighted average function; the other four ignore them. Pinning matters most for a composite you rely on in CI, where a silent change to a child would quietly move the gate.
+
+## Keep exploring
+
+<CardGroup cols={3}>
+  <Card title="Running Evaluations" icon="play-circle" href="/docs/evaluation/guides/running-evaluations">
+    Run a composite on any surface
+  </Card>
+  <Card title="Create a custom eval" icon="wand-magic-sparkles" href="/docs/evaluation/guides/custom-evals">
+    Write a child template of your own
+  </Card>
+  <Card title="Built-in evals" icon="tags" href="/docs/evaluation/builtin">
+    156 templates you can drop in as children
+  </Card>
+</CardGroup>

src/pages/docs/evaluation/concepts/error-localization.mdx

@@ -0,0 +1,41 @@
+---
+title: "Error localization"
+description: "Pinpoint which input field caused an evaluation to fail"
+---
+
+## Which input caused the failure
+
+When an evaluation fails, **error localization** narrows down the cause by analyzing which input field led to the failure, using the [evaluator model](/docs/evaluation/concepts/evaluator-models)'s explanation and the [eval template](/docs/evaluation/concepts/eval-templates)'s criteria. Instead of knowing only that an eval failed, you learn which input, whether the prompt, context, or query, was responsible, so you can see whether the problem is in your data, your retrieval, or your instructions. This works the same whether you're testing in the Playground or reviewing a live trace in [Observe](/docs/observe). You turn it on with the Error Localization checkbox when you configure an eval, on the template or a single run; see [Running Evaluations](/docs/evaluation/guides/running-evaluations) for the flow.
+
+## How it works
+
+1. **Evaluation fails**: error localization runs when a result comes back failed, pass/fail evals by their own verdict, scored evals on a low score.
+2. **Analysis**: an error-localizing agent receives the input data, the eval criteria, the eval result, and the evaluator model's explanation, then works out which input drove the failure.
+3. **Result**: you get back an `error_analysis` block describing the problem and a `selected_input_key` naming the input field identified as the issue.
+4. **Review**: the flagged field shows up in the trace detail eval view in Observe, and in the Playground's run tests.
+
+## When it runs
+
+Error localization runs on a failed result, as long as the eval isn't a code-type or composite eval. It's skipped when:
+
+- Evaluation passed, nothing to localize
+- Code-type eval, not supported
+- Composite eval, not supported yet
+
+## Where results appear
+
+- **Trace detail eval view**: looking at a span's eval result in Observe shows the flagged input and analysis inline
+- **Develop's dataset row drawer**: open a row on a dataset run to see the same breakdown
+- **Playground**: the Dataset, Trace, and Simulation test modes render it while you're testing a template
+- **SDK**: the result object returns `error_analysis` and `selected_input_key` directly
+
+## Keep exploring
+
+<CardGroup cols={2}>
+  <Card title="Running Evaluations" icon="play-circle" href="/docs/evaluation/guides/running-evaluations">
+    Run an eval and see error localization results
+  </Card>
+  <Card title="Eval templates & versions" icon="table-rows" href="/docs/evaluation/concepts/eval-templates">
+    Where the Error Localization checkbox lives on a template
+  </Card>
+</CardGroup>