fix(graders): fix typo in code_execution filename and imports (#54)

* fix(graders): fix typo in code_execution filename and imports

- Rename code_excution.py to code_execution.py (fix typo)
- Fix imports in code/__init__.py: open_judge -> openjudge
- Remove commented-out import in base_grader.py

* refactor(core): improve type hints, docstrings and error handling

- Fix doctest examples to use proper subclass instantiation
- Add type hints to concurrency.py run_with_concurrency_control
- Support list templates in LLMGrader initialization
- Fix DashScope formatter to handle empty lists correctly
- Improve PromptTemplate error messages for missing languages
- Use more specific exception types in utils modules
- Update test assertion for new template error message

* fix(graders): use relative imports and fix empty content handling

Author: XiaoBoAI

openjudge/graders/base_grader.py

@@ -6,7 +6,6 @@
 either scores or rankings.
 """
 
-# import inspect
 from abc import ABC, abstractmethod
 from typing import Any, Dict
 
@@ -60,7 +59,10 @@ def __init__(
                      accessible to subclasses.
 
         Example:
-            >>> grader = BaseGrader(
+            >>> class MyGrader(BaseGrader):
+            ...     async def aevaluate(self, **kwargs):
+            ...         pass
+            >>> grader = MyGrader(
             ...     name="accuracy_grader",
             ...     mode=GraderMode.POINTWISE,
             ...     description="Evaluates answer accuracy"
@@ -189,7 +191,12 @@ def from_config(
         # Extract standard grader properties from a copy to avoid mutating the input config
         config_copy = dict(config)
         name = config_copy.pop("name", "")
-        mode = config_copy.pop("mode", GraderMode.POINTWISE)
+        mode_value = config_copy.pop("mode", GraderMode.POINTWISE)
+        # Convert string to GraderMode if necessary
+        if isinstance(mode_value, str):
+            mode = GraderMode(mode_value)
+        else:
+            mode = mode_value
         description = config_copy.pop("description", "")
 
         # Create and return new instance with remaining config items as kwargs

openjudge/graders/code/__init__.py

@@ -8,10 +8,10 @@
 extensible evaluation mechanisms for AI-generated content.
 """
 
-from open_judge.graders.code.code_excution import CodeExecutionGrader
-from open_judge.graders.code.code_style import CodeStyleGrader
-from open_judge.graders.code.patch_similarity import PatchSimilarityGrader
-from open_judge.graders.code.syntax_checker import SyntaxCheckGrader
+from .code_execution import CodeExecutionGrader
+from .code_style import CodeStyleGrader
+from .patch_similarity import PatchSimilarityGrader
+from .syntax_checker import SyntaxCheckGrader
 
 __all__ = [
     "CodeExecutionGrader",

openjudge/graders/code/code_excution.py openjudge/graders/code/code_execution.pyopenjudge/graders/code/code_excution.py renamed to openjudge/graders/code/code_execution.py

@@ -133,10 +133,13 @@ def __init__(
             )
         elif isinstance(template, PromptTemplate):
             self.template = template
+        elif isinstance(template, list):
+            # Support list of message dicts or ChatMessage objects
+            self.template = PromptTemplate.from_prompt(template)
         elif isinstance(template, dict):
             self.template = PromptTemplate(**template)
         else:
-            raise ValueError("Template must be a str, dict or PromptTemplate object")
+            raise ValueError("Template must be a str, list, dict or PromptTemplate object")
 
         # Initialize model
         if isinstance(model, dict):

openjudge/graders/llm_grader.py

@@ -8,10 +8,10 @@
 - Text-to-image generation quality
 """
 
-from openjudge.graders.multimodal._internal import MLLMImage
-from openjudge.graders.multimodal.image_coherence import ImageCoherenceGrader
-from openjudge.graders.multimodal.image_helpfulness import ImageHelpfulnessGrader
-from openjudge.graders.multimodal.text_to_image import TextToImageGrader
+from ._internal import MLLMImage
+from .image_coherence import ImageCoherenceGrader
+from .image_helpfulness import ImageHelpfulnessGrader
+from .text_to_image import TextToImageGrader
 
 __all__ = [
     # Graders

openjudge/graders/multimodal/__init__.py

@@ -142,9 +142,10 @@ class GraderRank(GraderResult):
 
 
 class GraderRankCallback(BaseModel):
-    """Callback for grader rank result, used for .
+    """Callback schema for LLM structured output in listwise grading.
 
-    Represents a ranking of items assigned by a grader along with a reason.
+    Used as the structured_model parameter in LLMGrader for LISTWISE mode.
+    The LLM returns this schema which is then converted to GraderRank.
 
     Attributes:
         rank (List[int]): The ranking of items.

openjudge/graders/schema.py

@@ -29,7 +29,7 @@ class BaseChatModel(ABC):
         ...     async def achat(self, *args, **kwargs):
         ...         # Implementation here
         ...         pass
-        >>> model = MyChatModel(model="qwen3-max", stream=False)
+        >>> model = MyChatModel(model="qwen3-32b", stream=False)
         >>> print(model.model)
         qwen3-32b
     """
@@ -52,11 +52,12 @@ def __init__(
             stream: Whether the model output is streaming or not.
 
         Example:
-            >>> model = BaseChatModel(model="qwen3-32b", stream=True)
+            >>> class MyChatModel(BaseChatModel):
+            ...     async def achat(self, *args, **kwargs):
+            ...         pass
+            >>> model = MyChatModel(model="qwen3-32b", stream=True)
             >>> print(model.model)
             qwen3-32b
-            >>> print(model.stream)
-            True
         """
         self.model = model
         self.stream = stream
@@ -102,9 +103,11 @@ def _validate_tool_choice(
             ValueError: If tool_choice is invalid.
 
         Example:
-            >>> model = BaseChatModel(model="test", stream=False)
+            >>> class MyChatModel(BaseChatModel):
+            ...     async def achat(self, *args, **kwargs):
+            ...         pass
+            >>> model = MyChatModel(model="test", stream=False)
             >>> model._validate_tool_choice("auto", None)  # Valid
-            >>> # model._validate_tool_choice(123, None)  # Would raise TypeError
         """
         if not isinstance(tool_choice, str):
             raise TypeError(

openjudge/models/base_chat_model.py

@@ -83,7 +83,7 @@ def _convert_content_to_openai(
         if isinstance(content, str):
             return content
 
-        # If content is a list, process each part
+        # If content is a list, process each part (including empty list)
         if isinstance(content, list):
             openai_content = []
             for part in content:
@@ -143,7 +143,7 @@ def _convert_content_to_dashscope(
         if isinstance(content, str):
             return content
 
-        # If content is a list, process each part
+        # If content is a list, process each part (including empty list)
         if isinstance(content, list):
             dashscope_content = []
             for part in content:

openjudge/models/formatter/dashscope_formatter.py

@@ -167,9 +167,8 @@ def to_messages(
             List[ChatMessage]: The messages for the specified language.
 
         Raises:
-            AssertionError: If the specified language is not available in a
-                multilingual template.
-            ValueError: If messages format is invalid.
+            ValueError: If the specified language is not available in a
+                multilingual template, or if messages format is invalid.
 
         Examples:
             >>> template = PromptTemplate(messages=[ChatMessage(role="user", content="Hello")])
@@ -182,16 +181,17 @@ def to_messages(
             [ChatMessage(role="user", content="Hello")]
         """
         if isinstance(self.messages, list):
-            messages = self.messages
-        elif isinstance(self.messages, dict):
+            return self.messages
+
+        if isinstance(self.messages, dict):
             if not language:
                 language = LanguageEnum.EN
-            assert language in self.messages
-            messages = self.messages.get(language, [])
-        else:
-            raise ValueError("Invalid messages")
+            if language not in self.messages:
+                available = [lang.value for lang in self.messages.keys()]
+                raise ValueError(f"Language '{language.value}' not found. Available: {available}")
+            return self.messages[language]
 
-        return messages
+        raise ValueError("Invalid messages format")
 
     @classmethod
     def from_prompt(cls, prompt: Prompt) -> "PromptTemplate":
@@ -280,7 +280,7 @@ def format(
         messages = [message.format(**kwargs).to_dict() for message in messages]
         return messages
 
-    def get_prompt(self, language: LanguageEnum = None) -> Dict[str, List[Dict[str, str]]]:
+    def get_prompt(self, language: LanguageEnum | None = None) -> Dict[str, List[Dict[str, str]]]:
         """Return the core prompts (role, content) information of the messages,
         in a {language: list[{'role': txt, 'content': txt}]} dictionary.
         """

openjudge/models/schema/prompt_template.py

@@ -6,6 +6,9 @@
 """
 
 import asyncio
+from typing import Awaitable, TypeVar
+
+T = TypeVar("T")
 
 
 class ConcurrencyManager:
@@ -61,15 +64,15 @@ def get_max_concurrency(self) -> int:
         """
         return self._max_concurrency
 
-    async def run_with_concurrency_control(self, coro):
+    async def run_with_concurrency_control(self, coro: Awaitable[T]) -> T:
         """
         Run a coroutine with concurrency control.
 
         Args:
-            coro: The coroutine to run
+            coro: The coroutine to run.
 
         Returns:
-            The result of the coroutine
+            T: The result of the coroutine.
         """
         async with self._semaphore:
             return await coro