judgeval 0.16.9__py3-none-any.whl → 0.22.2__py3-none-any.whl

judgeval/__init__.py

@@ -6,6 +6,7 @@ from judgeval.data.evaluation_run import ExampleEvaluationRun
 
 
 from typing import List, Optional, Union, Sequence
+import ast
 from judgeval.scorers import ExampleAPIScorerConfig
 from judgeval.scorers.example_scorer import ExampleScorer
 from judgeval.data.example import Example
@@ -81,6 +82,7 @@ class JudgmentClient(metaclass=SingletonMeta):
         scorer_file_path: str,
         requirements_file_path: Optional[str] = None,
         unique_name: Optional[str] = None,
+        overwrite: bool = False,
     ) -> bool:
         """
         Upload custom ExampleScorer from files to backend.
@@ -89,6 +91,7 @@ class JudgmentClient(metaclass=SingletonMeta):
             scorer_file_path: Path to Python file containing CustomScorer class
             requirements_file_path: Optional path to requirements.txt
             unique_name: Optional unique identifier (auto-detected from scorer.name if not provided)
+            overwrite: Whether to overwrite existing scorer if it already exists
 
         Returns:
             bool: True if upload successful
@@ -111,6 +114,31 @@ class JudgmentClient(metaclass=SingletonMeta):
         with open(scorer_file_path, "r") as f:
             scorer_code = f.read()
 
+        try:
+            tree = ast.parse(scorer_code, filename=scorer_file_path)
+        except SyntaxError as e:
+            error_msg = f"Invalid Python syntax in {scorer_file_path}: {e}"
+            judgeval_logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        scorer_classes = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                for base in node.bases:
+                    if (isinstance(base, ast.Name) and base.id == "ExampleScorer") or (
+                        isinstance(base, ast.Attribute) and base.attr == "ExampleScorer"
+                    ):
+                        scorer_classes.append(node.name)
+
+        if len(scorer_classes) > 1:
+            error_msg = f"Multiple ExampleScorer classes found in {scorer_file_path}: {scorer_classes}. Please only upload one scorer class per file."
+            judgeval_logger.error(error_msg)
+            raise ValueError(error_msg)
+        elif len(scorer_classes) == 0:
+            error_msg = f"No ExampleScorer class was found in {scorer_file_path}. Please ensure the file contains a valid scorer class that inherits from ExampleScorer."
+            judgeval_logger.error(error_msg)
+            raise ValueError(error_msg)
+
         # Read requirements (optional)
         requirements_text = ""
         if requirements_file_path and os.path.exists(requirements_file_path):
@@ -118,6 +146,8 @@ class JudgmentClient(metaclass=SingletonMeta):
                 requirements_text = f.read()
 
         try:
+            if not self.api_key or not self.organization_id:
+                raise ValueError("Judgment API key and organization ID are required")
             client = JudgmentSyncClient(
                 api_key=self.api_key,
                 organization_id=self.organization_id,
@@ -127,6 +157,7 @@ class JudgmentClient(metaclass=SingletonMeta):
                     "scorer_name": unique_name,
                     "scorer_code": scorer_code,
                     "requirements_text": requirements_text,
+                    "overwrite": overwrite,
                 }
             )
 
@@ -139,8 +170,7 @@ class JudgmentClient(metaclass=SingletonMeta):
                 judgeval_logger.error(f"Failed to upload custom scorer: {unique_name}")
                 return False
 
-        except Exception as e:
-            judgeval_logger.error(f"Error uploading custom scorer: {e}")
+        except Exception:
             raise
 
 

judgeval/api/__init__.py

@@ -189,6 +189,59 @@ class JudgmentSyncClient:
             payload,
         )
 
+    def prompts_insert(self, payload: PromptInsertRequest) -> PromptInsertResponse:
+        return self._request(
+            "POST",
+            url_for("/prompts/insert/"),
+            payload,
+        )
+
+    def prompts_tag(self, payload: PromptTagRequest) -> PromptTagResponse:
+        return self._request(
+            "POST",
+            url_for("/prompts/tag/"),
+            payload,
+        )
+
+    def prompts_untag(self, payload: PromptUntagRequest) -> PromptUntagResponse:
+        return self._request(
+            "POST",
+            url_for("/prompts/untag/"),
+            payload,
+        )
+
+    def prompts_fetch(
+        self,
+        project_id: str,
+        name: str,
+        commit_id: Optional[str] = None,
+        tag: Optional[str] = None,
+    ) -> PromptFetchResponse:
+        query_params = {}
+        query_params["project_id"] = project_id
+        query_params["name"] = name
+        if commit_id is not None:
+            query_params["commit_id"] = commit_id
+        if tag is not None:
+            query_params["tag"] = tag
+        return self._request(
+            "GET",
+            url_for("/prompts/fetch/"),
+            query_params,
+        )
+
+    def prompts_get_prompt_versions(
+        self, project_id: str, name: str
+    ) -> PromptVersionsResponse:
+        query_params = {}
+        query_params["project_id"] = project_id
+        query_params["name"] = name
+        return self._request(
+            "GET",
+            url_for("/prompts/get_prompt_versions/"),
+            query_params,
+        )
+
     def projects_resolve(
         self, payload: ResolveProjectNameRequest
     ) -> ResolveProjectNameResponse:
@@ -381,6 +434,61 @@ class JudgmentAsyncClient:
             payload,
         )
 
+    async def prompts_insert(
+        self, payload: PromptInsertRequest
+    ) -> PromptInsertResponse:
+        return await self._request(
+            "POST",
+            url_for("/prompts/insert/"),
+            payload,
+        )
+
+    async def prompts_tag(self, payload: PromptTagRequest) -> PromptTagResponse:
+        return await self._request(
+            "POST",
+            url_for("/prompts/tag/"),
+            payload,
+        )
+
+    async def prompts_untag(self, payload: PromptUntagRequest) -> PromptUntagResponse:
+        return await self._request(
+            "POST",
+            url_for("/prompts/untag/"),
+            payload,
+        )
+
+    async def prompts_fetch(
+        self,
+        project_id: str,
+        name: str,
+        commit_id: Optional[str] = None,
+        tag: Optional[str] = None,
+    ) -> PromptFetchResponse:
+        query_params = {}
+        query_params["project_id"] = project_id
+        query_params["name"] = name
+        if commit_id is not None:
+            query_params["commit_id"] = commit_id
+        if tag is not None:
+            query_params["tag"] = tag
+        return await self._request(
+            "GET",
+            url_for("/prompts/fetch/"),
+            query_params,
+        )
+
+    async def prompts_get_prompt_versions(
+        self, project_id: str, name: str
+    ) -> PromptVersionsResponse:
+        query_params = {}
+        query_params["project_id"] = project_id
+        query_params["name"] = name
+        return await self._request(
+            "GET",
+            url_for("/prompts/get_prompt_versions/"),
+            query_params,
+        )
+
     async def projects_resolve(
         self, payload: ResolveProjectNameRequest
     ) -> ResolveProjectNameResponse:

judgeval/api/api_types.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  .openapi.json
-#   timestamp: 2025-10-15T19:25:00+00:00
+#   timestamp: 2025-10-25T22:30:20+00:00
 
 from __future__ import annotations
 from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
@@ -24,15 +24,6 @@ class DatasetsFetch(TypedDict):
     project_name: str
 
 
-class DatasetsTableRow(TypedDict):
-    dataset_id: str
-    name: str
-    created_at: str
-    kind: Literal["trace", "example"]
-    entries: int
-    creator: str
-
-
 class ProjectAdd(TypedDict):
     project_name: str
 
@@ -67,19 +58,16 @@ class SavePromptScorerRequest(TypedDict):
     description: NotRequired[Optional[str]]
 
 
-class SavePromptScorerResponse(TypedDict):
-    message: str
-    name: str
-
-
 class FetchPromptScorersRequest(TypedDict):
     names: NotRequired[Optional[List[str]]]
+    is_trace: NotRequired[Optional[bool]]
 
 
 class CustomScorerUploadPayload(TypedDict):
     scorer_name: str
     scorer_code: str
     requirements_text: str
+    overwrite: NotRequired[bool]
 
 
 class CustomScorerTemplateResponse(TypedDict):
@@ -88,6 +76,40 @@ class CustomScorerTemplateResponse(TypedDict):
     message: str
 
 
+class PromptInsertRequest(TypedDict):
+    project_id: str
+    name: str
+    prompt: str
+    tags: List[str]
+
+
+class PromptInsertResponse(TypedDict):
+    commit_id: str
+    parent_commit_id: NotRequired[Optional[str]]
+    created_at: str
+
+
+class PromptTagRequest(TypedDict):
+    project_id: str
+    name: str
+    commit_id: str
+    tags: List[str]
+
+
+class PromptTagResponse(TypedDict):
+    commit_id: str
+
+
+class PromptUntagRequest(TypedDict):
+    project_id: str
+    name: str
+    tags: List[str]
+
+
+class PromptUntagResponse(TypedDict):
+    commit_ids: List[str]
+
+
 class ResolveProjectNameRequest(TypedDict):
     project_name: str
 
@@ -158,6 +180,9 @@ DatasetKind = Literal["trace", "example"]
 
 
 class PromptScorer(TypedDict):
+    id: str
+    user_id: str
+    organization_id: str
     name: str
     prompt: str
     threshold: float
@@ -167,6 +192,19 @@ class PromptScorer(TypedDict):
     created_at: NotRequired[Optional[str]]
     updated_at: NotRequired[Optional[str]]
     is_trace: NotRequired[Optional[bool]]
+    is_bucket_rubric: NotRequired[Optional[bool]]
+
+
+class PromptCommitInfo(TypedDict):
+    name: str
+    prompt: str
+    tags: List[str]
+    commit_id: str
+    parent_commit_id: NotRequired[Optional[str]]
+    created_at: str
+    first_name: str
+    last_name: str
+    user_email: str
 
 
 class ScorerData(TypedDict):
@@ -245,6 +283,7 @@ class TraceEvaluationRun(TypedDict):
     created_at: NotRequired[str]
     trace_and_span_ids: List[TraceAndSpanId]
     is_offline: NotRequired[bool]
+    is_bucket_run: NotRequired[bool]
 
 
 class DatasetInsertExamples(TypedDict):
@@ -253,6 +292,15 @@ class DatasetInsertExamples(TypedDict):
     project_name: str
 
 
+class DatasetInfo(TypedDict):
+    dataset_id: str
+    name: str
+    created_at: str
+    kind: DatasetKind
+    entries: int
+    creator: str
+
+
 class DatasetCreate(TypedDict):
     name: str
     dataset_kind: DatasetKind
@@ -261,10 +309,22 @@ class DatasetCreate(TypedDict):
     overwrite: bool
 
 
+class SavePromptScorerResponse(TypedDict):
+    scorer_response: PromptScorer
+
+
 class FetchPromptScorersResponse(TypedDict):
     scorers: List[PromptScorer]
 
 
+class PromptFetchResponse(TypedDict):
+    commit: NotRequired[Optional[PromptCommitInfo]]
+
+
+class PromptVersionsResponse(TypedDict):
+    versions: List[PromptCommitInfo]
+
+
 class ScoringResult(TypedDict):
     success: bool
     scorers_data: List[ScorerData]
@@ -287,6 +347,7 @@ class OtelTraceListItem(TypedDict):
     llm_cost: NotRequired[Optional[float]]
     error: NotRequired[str]
     scores: NotRequired[List[OtelSpanListItemScores]]
+    rules_invoked: NotRequired[List[str]]
     customer_id: NotRequired[Optional[str]]
     input: NotRequired[Optional[str]]
     output: NotRequired[Optional[str]]

judgeval/cli.py

@@ -6,6 +6,7 @@ from dotenv import load_dotenv
 from judgeval.logger import judgeval_logger
 from judgeval import JudgmentClient
 from judgeval.version import get_version
+from judgeval.exceptions import JudgmentAPIError
 
 load_dotenv()
 
@@ -26,6 +27,12 @@ def upload_scorer(
     unique_name: str = typer.Option(
         None, help="Custom name for the scorer (auto-detected if not provided)"
     ),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        "-o",
+        help="Overwrite existing scorer if it already exists",
+    ),
 ):
     # Validate file paths
     if not Path(scorer_file_path).exists():
@@ -43,14 +50,22 @@ def upload_scorer(
             scorer_file_path=scorer_file_path,
             requirements_file_path=requirements_file_path,
             unique_name=unique_name,
+            overwrite=overwrite,
         )
 
         if not result:
             judgeval_logger.error("Failed to upload custom scorer")
             raise typer.Exit(1)
 
+        judgeval_logger.info("Custom scorer uploaded successfully!")
         raise typer.Exit(0)
-    except Exception:
+    except Exception as e:
+        if isinstance(e, JudgmentAPIError) and e.status_code == 409:
+            judgeval_logger.error(
+                "Duplicate scorer detected. Use --overwrite flag to replace the existing scorer"
+            )
+            raise typer.Exit(1)
+        # Re-raise other exceptions
         raise
 
 

judgeval/data/judgment_types.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  .openapi.json
-#   timestamp: 2025-10-15T19:24:59+00:00
+#   timestamp: 2025-10-25T22:30:19+00:00
 
 from __future__ import annotations
 from typing import Annotated, Any, Dict, List, Optional, Union
@@ -26,20 +26,6 @@ class DatasetsFetch(BaseModel):
     project_name: Annotated[str, Field(title="Project Name")]
 
 
-class Kind(Enum):
-    trace = "trace"
-    example = "example"
-
-
-class DatasetsTableRow(BaseModel):
-    dataset_id: Annotated[str, Field(title="Dataset Id")]
-    name: Annotated[str, Field(title="Name")]
-    created_at: Annotated[str, Field(title="Created At")]
-    kind: Annotated[Kind, Field(title="Kind")]
-    entries: Annotated[int, Field(title="Entries")]
-    creator: Annotated[str, Field(title="Creator")]
-
-
 class ProjectAdd(BaseModel):
     project_name: Annotated[str, Field(title="Project Name")]
 
@@ -74,19 +60,16 @@ class SavePromptScorerRequest(BaseModel):
     description: Annotated[Optional[str], Field(title="Description")] = None
 
 
-class SavePromptScorerResponse(BaseModel):
-    message: Annotated[str, Field(title="Message")]
-    name: Annotated[str, Field(title="Name")]
-
-
 class FetchPromptScorersRequest(BaseModel):
     names: Annotated[Optional[List[str]], Field(title="Names")] = None
+    is_trace: Annotated[Optional[bool], Field(title="Is Trace")] = None
 
 
 class CustomScorerUploadPayload(BaseModel):
     scorer_name: Annotated[str, Field(title="Scorer Name")]
     scorer_code: Annotated[str, Field(title="Scorer Code")]
     requirements_text: Annotated[str, Field(title="Requirements Text")]
+    overwrite: Annotated[Optional[bool], Field(title="Overwrite")] = False
 
 
 class CustomScorerTemplateResponse(BaseModel):
@@ -95,6 +78,40 @@ class CustomScorerTemplateResponse(BaseModel):
     message: Annotated[str, Field(title="Message")]
 
 
+class PromptInsertRequest(BaseModel):
+    project_id: Annotated[str, Field(title="Project Id")]
+    name: Annotated[str, Field(title="Name")]
+    prompt: Annotated[str, Field(title="Prompt")]
+    tags: Annotated[List[str], Field(title="Tags")]
+
+
+class PromptInsertResponse(BaseModel):
+    commit_id: Annotated[str, Field(title="Commit Id")]
+    parent_commit_id: Annotated[Optional[str], Field(title="Parent Commit Id")] = None
+    created_at: Annotated[str, Field(title="Created At")]
+
+
+class PromptTagRequest(BaseModel):
+    project_id: Annotated[str, Field(title="Project Id")]
+    name: Annotated[str, Field(title="Name")]
+    commit_id: Annotated[str, Field(title="Commit Id")]
+    tags: Annotated[List[str], Field(title="Tags")]
+
+
+class PromptTagResponse(BaseModel):
+    commit_id: Annotated[str, Field(title="Commit Id")]
+
+
+class PromptUntagRequest(BaseModel):
+    project_id: Annotated[str, Field(title="Project Id")]
+    name: Annotated[str, Field(title="Name")]
+    tags: Annotated[List[str], Field(title="Tags")]
+
+
+class PromptUntagResponse(BaseModel):
+    commit_ids: Annotated[List[str], Field(title="Commit Ids")]
+
+
 class ResolveProjectNameRequest(BaseModel):
     project_name: Annotated[str, Field(title="Project Name")]
 
@@ -176,6 +193,9 @@ class DatasetKind(Enum):
 
 
 class PromptScorer(BaseModel):
+    id: Annotated[str, Field(title="Id")]
+    user_id: Annotated[str, Field(title="User Id")]
+    organization_id: Annotated[str, Field(title="Organization Id")]
     name: Annotated[str, Field(title="Name")]
     prompt: Annotated[str, Field(title="Prompt")]
     threshold: Annotated[float, Field(title="Threshold")]
@@ -185,6 +205,19 @@ class PromptScorer(BaseModel):
     created_at: Annotated[Optional[AwareDatetime], Field(title="Created At")] = None
     updated_at: Annotated[Optional[AwareDatetime], Field(title="Updated At")] = None
     is_trace: Annotated[Optional[bool], Field(title="Is Trace")] = False
+    is_bucket_rubric: Annotated[Optional[bool], Field(title="Is Bucket Rubric")] = None
+
+
+class PromptCommitInfo(BaseModel):
+    name: Annotated[str, Field(title="Name")]
+    prompt: Annotated[str, Field(title="Prompt")]
+    tags: Annotated[List[str], Field(title="Tags")]
+    commit_id: Annotated[str, Field(title="Commit Id")]
+    parent_commit_id: Annotated[Optional[str], Field(title="Parent Commit Id")] = None
+    created_at: Annotated[str, Field(title="Created At")]
+    first_name: Annotated[str, Field(title="First Name")]
+    last_name: Annotated[str, Field(title="Last Name")]
+    user_email: Annotated[str, Field(title="User Email")]
 
 
 class ScorerData(BaseModel):
@@ -279,6 +312,7 @@ class TraceEvaluationRun(BaseModel):
         List[TraceAndSpanId], Field(title="Trace And Span Ids")
     ]
     is_offline: Annotated[Optional[bool], Field(title="Is Offline")] = False
+    is_bucket_run: Annotated[Optional[bool], Field(title="Is Bucket Run")] = False
 
 
 class DatasetInsertExamples(BaseModel):
@@ -287,6 +321,15 @@ class DatasetInsertExamples(BaseModel):
     project_name: Annotated[str, Field(title="Project Name")]
 
 
+class DatasetInfo(BaseModel):
+    dataset_id: Annotated[str, Field(title="Dataset Id")]
+    name: Annotated[str, Field(title="Name")]
+    created_at: Annotated[str, Field(title="Created At")]
+    kind: DatasetKind
+    entries: Annotated[int, Field(title="Entries")]
+    creator: Annotated[str, Field(title="Creator")]
+
+
 class DatasetCreate(BaseModel):
     name: Annotated[str, Field(title="Name")]
     dataset_kind: DatasetKind
@@ -295,10 +338,22 @@ class DatasetCreate(BaseModel):
     overwrite: Annotated[bool, Field(title="Overwrite")]
 
 
+class SavePromptScorerResponse(BaseModel):
+    scorer_response: PromptScorer
+
+
 class FetchPromptScorersResponse(BaseModel):
     scorers: Annotated[List[PromptScorer], Field(title="Scorers")]
 
 
+class PromptFetchResponse(BaseModel):
+    commit: Optional[PromptCommitInfo] = None
+
+
+class PromptVersionsResponse(BaseModel):
+    versions: Annotated[List[PromptCommitInfo], Field(title="Versions")]
+
+
 class ScoringResult(BaseModel):
     success: Annotated[bool, Field(title="Success")]
     scorers_data: Annotated[List[ScorerData], Field(title="Scorers Data")]
@@ -325,6 +380,7 @@ class OtelTraceListItem(BaseModel):
     scores: Annotated[
         Optional[List[OtelSpanListItemScores]], Field(title="Scores")
     ] = []
+    rules_invoked: Annotated[Optional[List[str]], Field(title="Rules Invoked")] = []
     customer_id: Annotated[Optional[str], Field(title="Customer Id")] = None
     input: Annotated[Optional[str], Field(title="Input")] = None
     output: Annotated[Optional[str], Field(title="Output")] = None

judgeval/dataset/__init__.py

@@ -32,8 +32,8 @@ class Dataset:
     dataset_kind: DatasetKind = DatasetKind.example
     examples: Optional[List[Example]] = None
     traces: Optional[List[Trace]] = None
-    judgment_api_key: str = JUDGMENT_API_KEY or ""
-    organization_id: str = JUDGMENT_ORG_ID or ""
+    judgment_api_key: str | None = JUDGMENT_API_KEY
+    organization_id: str | None = JUDGMENT_ORG_ID
 
     @classmethod
     def get(
@@ -41,6 +41,8 @@ class Dataset:
         name: str,
         project_name: str,
     ):
+        if not cls.judgment_api_key or not cls.organization_id:
+            raise ValueError("Judgment API key and organization ID are required")
         client = JudgmentSyncClient(cls.judgment_api_key, cls.organization_id)
         dataset = client.datasets_pull_for_judgeval(
             {
@@ -102,6 +104,8 @@ class Dataset:
         examples: List[Example] = [],
         overwrite: bool = False,
     ):
+        if not cls.judgment_api_key or not cls.organization_id:
+            raise ValueError("Judgment API key and organization ID are required")
         if not examples:
             examples = []
 
@@ -125,6 +129,8 @@ class Dataset:
 
     @classmethod
     def list(cls, project_name: str):
+        if not cls.judgment_api_key or not cls.organization_id:
+            raise ValueError("Judgment API key and organization ID are required")
         client = JudgmentSyncClient(cls.judgment_api_key, cls.organization_id)
         datasets = client.datasets_pull_all_for_judgeval({"project_name": project_name})
 
@@ -173,6 +179,9 @@ class Dataset:
         if not isinstance(examples, list):
             raise TypeError("examples must be a list")
 
+        if not self.judgment_api_key or not self.organization_id:
+            raise ValueError("Judgment API key and organization ID are required")
+
         client = JudgmentSyncClient(self.judgment_api_key, self.organization_id)
         client.datasets_insert_examples_for_judgeval(
             {

judgeval/env.py

@@ -19,17 +19,8 @@ def optional_env_var(var_name: str, default: str | None = None) -> str | None:
     return os.getenv(var_name, default)
 
 
-def required_env_var(var_name: str) -> str:
-    value = os.getenv(var_name)
-    if value is None:
-        raise EnvironmentError(
-            f"Environment variable '{var_name}' is required but not set."
-        )
-    return value
-
-
-JUDGMENT_API_KEY = required_env_var("JUDGMENT_API_KEY")
-JUDGMENT_ORG_ID = required_env_var("JUDGMENT_ORG_ID")
+JUDGMENT_API_KEY = optional_env_var("JUDGMENT_API_KEY")
+JUDGMENT_ORG_ID = optional_env_var("JUDGMENT_ORG_ID")
 JUDGMENT_API_URL = optional_env_var("JUDGMENT_API_URL", "https://api.judgmentlabs.ai")
 
 JUDGMENT_DEFAULT_GPT_MODEL = optional_env_var("JUDGMENT_DEFAULT_GPT_MODEL", "gpt-5")

judgeval/evaluation/__init__.py

@@ -112,6 +112,8 @@ def _poll_evaluation_until_complete(
 
     poll_count = 0
     exception_count = 0
+    if not JUDGMENT_API_KEY or not JUDGMENT_ORG_ID:
+        raise ValueError("Judgment API key and organization ID are required")
     api_client = JudgmentSyncClient(JUDGMENT_API_KEY, JUDGMENT_ORG_ID)
     while poll_count < max_poll_count:
         poll_count += 1
@@ -222,6 +224,8 @@ def run_eval(
         )
         t.start()
         try:
+            if not JUDGMENT_API_KEY or not JUDGMENT_ORG_ID:
+                raise ValueError("Judgment API key and organization ID are required")
             api_client = JudgmentSyncClient(JUDGMENT_API_KEY, JUDGMENT_ORG_ID)
             response = api_client.add_to_run_eval_queue_examples(
                 evaluation_run.model_dump(warnings=False)  # type: ignore