Chore: [GSK-4543] Introduce specific error classes (e.g., CounterpointConfigError)

src/counterpoint/__init__.py

@@ -1,5 +1,11 @@
 from .chat import Chat, Message
 from .context import RunContext
+from .exceptions import (
+    CounterpointConfigError,
+    CounterpointError,
+    ToolError,
+    ToolDefinitionError,
+)
 from .generators import Generator
 from .pipeline import Pipeline
 from .rate_limiter import RateLimiter, RateLimiterStrategy
@@ -19,4 +25,8 @@
     "RateLimiterStrategy",
     "RateLimiter",
     "RunContext",
+    "CounterpointError",
+    "CounterpointConfigError",
+    "ToolError",
+    "ToolDefinitionError",
 ]

src/counterpoint/chat.py

@@ -4,6 +4,7 @@
 from pydantic import BaseModel, Field
 
 from counterpoint.context import RunContext
+from counterpoint.exceptions import CounterpointConfigError
 from counterpoint.tools import ToolCall
 
 Role = Literal["assistant", "user", "system", "tool"]
@@ -81,6 +82,15 @@ def transcript(self) -> str:
 
     @property
     def output(self) -> OutputType:
+        """Parsed output as the configured model.
+
+        Raises
+        ------
+        CounterpointConfigError
+            If no `output_model` is configured on the chat/pipeline.
+        """
         if self.output_model is None:
-            raise ValueError("Output model not set")
+            raise CounterpointConfigError(
+                "Output model not set. Call Pipeline.with_output(...) before accessing Chat.output."
+            )
         return self.last.parse(self.output_model)

src/counterpoint/exceptions.py

@@ -0,0 +1,23 @@
+"""Counterpoint-specific exception classes.
+
+These exceptions provide clearer error semantics for configuration,
+template, tool, parsing, and pipeline related issues compared to using
+generic built-ins.
+"""
+
+
+class CounterpointError(Exception):
+    """Base class for all Counterpoint errors."""
+
+
+class CounterpointConfigError(CounterpointError):
+    """Raised for invalid or missing configuration/state in Counterpoint."""
+
+
+class ToolError(CounterpointError):
+    """Base class for tool-related errors."""
+
+
+class ToolDefinitionError(ToolError):
+    """Raised when a tool is defined incorrectly (e.g., bad annotations)."""
+

src/counterpoint/rate_limiter.py

@@ -5,6 +5,8 @@
 
 from pydantic import BaseModel, Field, PrivateAttr
 
+from .exceptions import CounterpointConfigError
+
 
 class RateLimiterStrategy(BaseModel):
     min_interval: float
@@ -91,7 +93,7 @@ def _register_rate_limiter(rate_limiter: RateLimiter) -> None:
 def get_rate_limiter(
     rate_limiter_id: str,
 ) -> RateLimiter:
-    """Get or create a rate limiter.
+    """Get a rate limiter by id.
 
     Parameters
     ----------
@@ -102,8 +104,15 @@ def get_rate_limiter(
     -------
     RateLimiter
         The rate limiter.
+
+    Raises
+    ------
+    CounterpointConfigError
+        If a rate limiter with the given id is not registered.
     """
     try:
         return _rate_limiters[rate_limiter_id]
     except KeyError as err:
-        raise ValueError(f"Rate limiter with id {rate_limiter_id} not found") from err
+        raise CounterpointConfigError(
+            f"Rate limiter with id {rate_limiter_id} not found"
+        ) from err

src/counterpoint/templates/prompts_manager.py

@@ -5,6 +5,7 @@
 from pydantic import BaseModel, Field
 
 from counterpoint.chat import Message
+from counterpoint.exceptions import CounterpointConfigError
 
 from .environment import create_message_environment
 
@@ -35,7 +36,7 @@ async def render_messages_template(
     # 2. There are no message blocks. In this case, we will create a single user message with the rendered output.
     if messages:
         if rendered_output.strip():
-            raise ValueError(
+            raise CounterpointConfigError(
                 "Template contains message blocks but rendered output is not empty."
             )
         return messages

src/counterpoint/tools/tool.py

@@ -7,6 +7,7 @@
 from pydantic import BaseModel, Field, create_model
 
 from counterpoint.context import RunContext
+from counterpoint.exceptions import ToolDefinitionError
 
 from ._docstring_parser import parse_docstring
 
@@ -54,7 +55,7 @@ def from_callable(cls, fn: Callable) -> "Tool":
 
         Raises
         ------
-        ValueError
+        ToolDefinitionError
             If the function lacks proper annotations or docstring.
         """
         sig = inspect.signature(fn)
@@ -65,7 +66,7 @@ def from_callable(cls, fn: Callable) -> "Tool":
 
         for name, param in sig.parameters.items():
             if param.annotation is inspect.Parameter.empty:
-                raise ValueError(
+                raise ToolDefinitionError(
                     f"Tool `{fn.__name__}` parameter `{name}` must have a type annotation"
                 )
 

tests/test_chat.py

@@ -2,6 +2,7 @@
 from pydantic import BaseModel
 
 from counterpoint.chat import Chat, Message
+from counterpoint.exceptions import CounterpointConfigError
 
 
 def test_chat_output():
@@ -33,5 +34,5 @@ def test_chat_output_without_output_model():
     ]
 
     chat = Chat(messages=messages)
-    with pytest.raises(ValueError):
+    with pytest.raises(CounterpointConfigError):
         chat.output

tests/test_templates.py

@@ -40,7 +40,9 @@ async def test_multi_message_template_parsing(prompts_manager):
 
 
 async def test_invalid_template(prompts_manager):
-    with pytest.raises(ValueError):
+    from counterpoint.exceptions import CounterpointConfigError
+
+    with pytest.raises(CounterpointConfigError):
         await prompts_manager.render_template("invalid.j2")