feat(analytics): classify WriteError hierarchy out of unknown

src/opik_mcp/analytics/wrappers.py

@@ -37,6 +37,15 @@
     OpikServerError,
     OpikValidationError,
 )
+from opik_mcp.writes.errors import (
+    AuthorizationDeniedError,
+    BackendError,
+    BatchPartialFailureError,
+    BatchTooLargeError,
+    UnknownOperationError,
+    ValidationFailedError,
+    WriteError,
+)
 
 logger = logging.getLogger("opik_mcp.analytics.wrappers")
 
@@ -74,14 +83,30 @@
     (PodNotReadyError, "pod_warmup_timeout"),
     (OllieAuthError, "ollie_auth_failed"),
     (OllieStreamError, "ollie_stream_error"),
-    # Pydantic validation from INSIDE the tool body — e.g.
+    # `write` tool's structured error hierarchy — listed BEFORE the generic
+    # pydantic row because the dispatcher catches ``ValidationError`` from
+    # ``op.pydantic_model.model_validate(...)`` and re-raises it as
+    # ``ValidationFailedError`` (not a pydantic subclass), so the inner
+    # pydantic error never reaches this classifier on the write path.
+    # Bucket names mirror the stable ``ErrorCode`` literals declared in
+    # ``writes/errors.py`` so BI dashboards can key off the same enum used
+    # in the tool result envelope.
+    (ValidationFailedError, "write_validation_failed"),
+    (UnknownOperationError, "write_unknown_operation"),
+    (AuthorizationDeniedError, "write_authorization_denied"),
+    (BatchTooLargeError, "write_batch_too_large"),
+    (BatchPartialFailureError, "write_batch_partial_failure"),
+    (BackendError, "write_backend_error"),
+    (WriteError, "write_error_other"),  # catch-all for future subclasses
+    # Pydantic validation from INSIDE the tool body. Active path:
     # ``RunExperimentConfig.model_validate(experiment_config)`` in
-    # ``server.run_experiment`` or ``op.pydantic_model.model_validate(data)``
-    # in the write dispatcher. NOTE: FastMCP's ``Tool.run`` validates the
-    # tool's outer signature BEFORE calling our wrapped function and converts
-    # the resulting ``ValidationError`` into a ``ToolError``, so the very
-    # outermost arg-coercion failure never hits this branch. The bucket only
-    # fires when a tool itself calls ``model_validate`` on a sub-payload.
+    # ``server.run_experiment`` — a raw pydantic error there propagates
+    # directly to us. The write dispatcher's ``model_validate`` calls are
+    # NOT covered here because dispatch wraps them in ``ValidationFailedError``
+    # (handled above). NOTE: FastMCP's ``Tool.run`` validates the tool's
+    # outer signature BEFORE calling our wrapped function and converts the
+    # resulting ``ValidationError`` into a ``ToolError``, so the outermost
+    # arg-coercion failure never hits this branch either.
     (PydanticValidationError, "tool_args_invalid"),
     # Network — httpx.RequestError is the common base for ConnectError,
     # TimeoutException (read/connect/write/pool), ReadError, etc. Catches the

tests/test_analytics_wrappers.py

@@ -22,6 +22,15 @@
     OpikServerError,
     OpikValidationError,
 )
+from opik_mcp.writes.errors import (
+    AuthorizationDeniedError,
+    BackendError,
+    BatchPartialFailureError,
+    BatchTooLargeError,
+    UnknownOperationError,
+    ValidationFailedError,
+    WriteError,
+)
 
 
 def _build_pydantic_error() -> PydanticValidationError:
@@ -99,8 +108,33 @@ async def fn() -> str:
         (httpx.ConnectError("connect refused"), "network_error"),
         (httpx.ReadTimeout("read timed out"), "network_error"),
         (httpx.ReadError("read error"), "network_error"),
-        # pydantic validation on tool args.
+        # pydantic validation on tool args (raw pydantic, e.g. from
+        # ``RunExperimentConfig.model_validate(...)``).
         (_build_pydantic_error(), "tool_args_invalid"),
+        # `write` tool structured errors — dispatcher wraps inner pydantic
+        # failures in ValidationFailedError, so the bucket must surface as
+        # write_validation_failed rather than tool_args_invalid.
+        (
+            ValidationFailedError.build("score.create", [], expected_schema={}, example={}),
+            "write_validation_failed",
+        ),
+        (UnknownOperationError.build("bogus.op", ("score.create",)), "write_unknown_operation"),
+        (
+            AuthorizationDeniedError.build("score.create", "write:scores"),
+            "write_authorization_denied",
+        ),
+        (BatchTooLargeError.build("score.create", 5000, 1000), "write_batch_too_large"),
+        (
+            BatchPartialFailureError.build("score.create", [], []),
+            "write_batch_partial_failure",
+        ),
+        (
+            BackendError.build("score.create", 500, {}, method="POST", path="/v1/x"),
+            "write_backend_error",
+        ),
+        # Bare WriteError (future subclass / direct instance) falls into the
+        # catch-all bucket rather than "unknown".
+        (WriteError(error="backend_error"), "write_error_other"),
         # Genuine catch-all.
         (ValueError("x"), "unknown"),
     ],