From 01175450e42a08d7c5651c5ac61b09b8c8525a70 Mon Sep 17 00:00:00 2001
From: Sebastian Crossa <sebastiancrossa@hotmail.com>
Date: Wed, 21 Jan 2026 17:45:12 -0600
Subject: [PATCH 1/2] rename behaviors to judges

---
 docs.json                                  | 8 ++++----
 index.mdx                                  | 4 ++--
 {behaviors => judges}/introduction.mdx     | 6 +++---
 {behaviors => judges}/pull-evaluations.mdx | 6 +++---
 {behaviors => judges}/setup.mdx            | 4 ++--
 5 files changed, 14 insertions(+), 14 deletions(-)
 rename {behaviors => judges}/introduction.mdx (59%)
 rename {behaviors => judges}/pull-evaluations.mdx (97%)
 rename {behaviors => judges}/setup.mdx (84%)

diff --git a/docs.json b/docs.json
index 0cfa907..d03cfc6 100644
--- a/docs.json
+++ b/docs.json
@@ -66,12 +66,12 @@
             ]
           },
           {
-            "group": "Behaviors",
+            "group": "Judges",
             "icon": "gavel",
             "pages": [
-              "behaviors/introduction",
-              "behaviors/setup",
-              "behaviors/pull-evaluations"
+              "judges/introduction",
+              "judges/setup",
+              "judges/pull-evaluations"
             ]
           },
           {
diff --git a/index.mdx b/index.mdx
index 12fed3f..81f42a8 100644
--- a/index.mdx
+++ b/index.mdx
@@ -19,9 +19,9 @@ description: "Start improving your AI applications with ZeroEval"
     performance
   </Card>
   <Card
-    title="Behaviors"
+    title="Judges"
     icon="gavel"
-    href="/behaviors/introduction"
+    href="/judges/introduction"
   >
     Get reliable AI evaluation with judges that are calibrated to human
     preferences
diff --git a/behaviors/introduction.mdx b/judges/introduction.mdx
similarity index 59%
rename from behaviors/introduction.mdx
rename to judges/introduction.mdx
index 54822e7..d2d4b05 100644
--- a/behaviors/introduction.mdx
+++ b/judges/introduction.mdx
@@ -5,12 +5,12 @@ description: "Continuously evaluate your production traffic with judges that lea
 
 <video src="/videos/calibrated-judge.mp4" controls muted playsInline loop preload="metadata" />
 
-Calibrated LLM judges are AI evaluators that watch your traces, sessions, or spans and score behavior according to criteria you define. They get better over time the more you refine and correct their evaluations.
+Calibrated LLM judges are AI evaluators that watch your traces, sessions, or spans and score outputs according to criteria you define. They get better over time the more you refine and correct their evaluations.
 
 ## When to use
 
-Use a behavior when you want consistent, scalable evaluation of:
+Use a judge when you want consistent, scalable evaluation of:
 
 - Hallucinations, safety/policy violations
 - Response quality (helpfulness, tone, structure)
-- Latency, cost, and error patterns tied to behaviors
\ No newline at end of file
+- Latency, cost, and error patterns tied to specific criteria
diff --git a/behaviors/pull-evaluations.mdx b/judges/pull-evaluations.mdx
similarity index 97%
rename from behaviors/pull-evaluations.mdx
rename to judges/pull-evaluations.mdx
index 0fbdb30..7c42266 100644
--- a/behaviors/pull-evaluations.mdx
+++ b/judges/pull-evaluations.mdx
@@ -26,7 +26,7 @@ import zeroeval as ze
 
 ze.init(api_key="YOUR_API_KEY")
 
-response = ze.get_behavior_evaluations(
+response = ze.get_judge_evaluations(
     project_id="your-project-id",
     judge_id="your-judge-id",
     limit=100,
@@ -44,7 +44,7 @@ for eval in response["evaluations"]:
 **Optional filters:**
 
 ```python
-response = ze.get_behavior_evaluations(
+response = ze.get_judge_evaluations(
     project_id="your-project-id",
     judge_id="your-judge-id",
     limit=100,
@@ -150,7 +150,7 @@ offset = 0
 limit = 100
 
 while True:
-    response = ze.get_behavior_evaluations(
+    response = ze.get_judge_evaluations(
         project_id="your-project-id",
         judge_id="your-judge-id",
         limit=limit,
diff --git a/behaviors/setup.mdx b/judges/setup.mdx
similarity index 84%
rename from behaviors/setup.mdx
rename to judges/setup.mdx
index 39f2466..184e92f 100644
--- a/behaviors/setup.mdx
+++ b/judges/setup.mdx
@@ -7,8 +7,8 @@ description: "Create and calibrate an AI judge in minutes"
 
 ## Creating a judge (&lt;5 mins)
 
-1. Go to [Monitoring → Judges → New Judge](https://app.zeroeval.com/monitoring/signal-automations).
-2. Sepcify the behaviour that you want to track from your production traffic.
+1. Go to [Monitoring → Judges → New Judge](https://app.zeroeval.com/monitoring/judges).
+2. Specify the criteria that you want to evaluate from your production traffic.
 3. Tweak the prompt of the judge until it matches what you are looking for!
 
 That's it! Historical and future traces will be scored automatically and shown in the dashboard.

From 429ccc18fad3a5879d364f5b1a29674000aa8b69 Mon Sep 17 00:00:00 2001
From: Sebastian Crossa <sebastiancrossa@hotmail.com>
Date: Thu, 22 Jan 2026 09:52:09 -0600
Subject: [PATCH 2/2] update

---
 docs.json                   |   1 +
 judges/pull-evaluations.mdx |   4 ++
 judges/submit-feedback.mdx  | 119 ++++++++++++++++++++++++++++++++++++
 3 files changed, 124 insertions(+)
 create mode 100644 judges/submit-feedback.mdx

diff --git a/docs.json b/docs.json
index d03cfc6..b722932 100644
--- a/docs.json
+++ b/docs.json
@@ -71,6 +71,7 @@
             "pages": [
               "judges/introduction",
               "judges/setup",
+              "judges/submit-feedback",
               "judges/pull-evaluations"
             ]
           },
diff --git a/judges/pull-evaluations.mdx b/judges/pull-evaluations.mdx
index 7c42266..e582bd6 100644
--- a/judges/pull-evaluations.mdx
+++ b/judges/pull-evaluations.mdx
@@ -166,3 +166,7 @@ while True:
 
 print(f"Fetched {len(all_evaluations)} total evaluations")
 ```
+
+## Related
+
+- [Submitting Feedback](/judges/submit-feedback) - Programmatically submit feedback for judge evaluations
diff --git a/judges/submit-feedback.mdx b/judges/submit-feedback.mdx
new file mode 100644
index 0000000..3167f4f
--- /dev/null
+++ b/judges/submit-feedback.mdx
@@ -0,0 +1,119 @@
+---
+title: "Submitting Feedback"
+description: "Programmatically submit feedback for judge evaluations via SDK"
+---
+
+## Overview
+
+When calibrating judges, you can submit feedback programmatically using the SDK.
+This is useful for:
+
+- Bulk feedback submission from automated pipelines
+- Integration with custom review workflows
+- Syncing feedback from external labeling tools
+
+## Important: Using the Correct IDs
+
+Judge evaluations involve two related spans:
+
+| ID | Description |
+|---|---|
+| **Source Span ID** | The original LLM call that was evaluated |
+| **Judge Call Span ID** | The span created when the judge ran its evaluation |
+
+When submitting feedback, always include the `judge_id` parameter to ensure
+feedback is correctly associated with the judge evaluation.
+
+## Python SDK
+
+### From the UI (Recommended)
+
+The easiest way to get the correct IDs is from the Judge Evaluation modal:
+
+1. Open a judge evaluation in the dashboard
+2. Expand the "SDK Integration" section
+3. Click "Copy" to copy the pre-filled Python code
+4. Paste and customize the generated code
+
+### Manual Submission
+
+```python
+from zeroeval import ZeroEval
+
+client = ZeroEval()
+
+# Submit feedback for a judge evaluation
+client.send_feedback(
+    prompt_slug="your-judge-task-slug",  # The task/prompt associated with the judge
+    completion_id="span-id-here",         # The span ID from the evaluation
+    thumbs_up=True,                        # True = correct, False = incorrect
+    reason="Optional explanation",
+    judge_id="automation-id-here",         # Required for judge feedback
+)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `prompt_slug` | str | Yes | The task slug associated with the judge |
+| `completion_id` | str | Yes | The span ID being evaluated |
+| `thumbs_up` | bool | Yes | `True` if judge was correct, `False` if wrong |
+| `reason` | str | No | Explanation of the feedback |
+| `judge_id` | str | Yes* | The judge automation ID (*required for judge feedback) |
+
+## REST API
+
+```bash
+curl -X POST "https://api.zeroeval.com/v1/prompts/{task_slug}/completions/{span_id}/feedback" \
+  -H "Authorization: Bearer $ZEROEVAL_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "thumbs_up": true,
+    "reason": "Judge correctly identified the issue",
+    "judge_id": "automation-uuid-here"
+  }'
+```
+
+## Finding Your IDs
+
+| ID | Where to Find It |
+|---|---|
+| **Task Slug** | In the judge settings, or the URL when editing the judge's prompt |
+| **Span ID** | In the evaluation modal, or via `get_judge_evaluations()` response |
+| **Judge ID** | In the URL when viewing a judge (`/judges/{judge_id}`) |
+
+## Bulk Feedback Submission
+
+For submitting feedback on multiple evaluations, you can iterate through evaluations:
+
+```python
+from zeroeval import ZeroEval
+
+client = ZeroEval()
+
+# Get evaluations to review
+evaluations = client.get_judge_evaluations(
+    project_id="your-project-id",
+    judge_id="your-judge-id",
+    limit=100,
+)
+
+# Submit feedback for each
+for eval in evaluations["evaluations"]:
+    # Your logic to determine if the evaluation was correct
+    is_correct = your_review_logic(eval)
+    
+    client.send_feedback(
+        prompt_slug="your-judge-task-slug",
+        completion_id=eval["span_id"],
+        thumbs_up=is_correct,
+        reason="Automated review",
+        judge_id="your-judge-id",
+    )
+```
+
+## Related
+
+- [Pulling Evaluations](/judges/pull-evaluations) - Retrieve judge evaluations programmatically
+- [Judge Setup](/judges/setup) - Configure and deploy judges