feat: centralized error management with Data360MCPError hierarchy

[rafmacalaba]

Summary

Addresses #19

Note

This branch is based on feat/improve-tool-descriptions (not yet merged to dev). Merge that branch first before merging this PR.

Centralizes error management by introducing a Data360MCPError class hierarchy, replacing scattered try/except blocks across the codebase with structured, LLM-actionable error responses.

Changes

src/data360/errors.py [NEW]

• Data360MCPError base exception with error_code, detail, and to_dict() serialization
• Subclasses: APIError, Data360TimeoutError, RequestError, ParseError, ValidationError, NotFoundError
• classify_error() converter for clean exception handling
• Message registry mapping error codes to LLM-actionable messages

src/data360/api.py

• Refactored _search_raw(), get_metadata(), get_disaggregation(), get_data() to raise/catch Data360MCPError subclasses instead of raw exceptions

src/data360/visualization.py

• get_viz_spec now returns a "warning" key when Draco fails to find an optimal encoding and a fallback line chart is generated

tests/test_errors.py [NEW]

• 18 tests covering all error classes and classify_error mapping logic

tests/test_visualization.py [NEW]

• 3 tests: fallback returns warning, Draco success has no warning, both-fail returns error

tests/test_api.py

• Updated assertions to match new error message format

Test Results

All 41 tests pass with no regressions.

[avsolatorio]

lgtm!

Not a blocker, but wondering what your view is about adding the logging to the Data360MCPError? Essentially, creating an instance of the Data360MCPError with an optional logger argument automatically logs self.detail after super().__init__(self.detail).

[rafmacalaba]

My view is that it's worth doing, the current code has inconsistent coverage, where directly constructed errors like NotFoundError and ValidationError have no logging at all while some call sites log manually. The suggestion closes that gap cleanly.

The one thing I'd adjust is the mechanism: rather than an injected logger argument (which still requires callers to opt in), I'd prefer a module-level _logger in errors.py that logs unconditionally in __init__. Same outcome, no risk of a call site forgetting to pass the logger. I'd also add a log_level class attribute so subclasses like NotFoundError can log at WARNING instead of ERROR — a 'no results found' condition shouldn't show up in error dashboards.

Implemented this.

[avsolatorio]

Hello @rafmacalaba , thank you for considering adding the centralized logging for the errors! Wanted to merge this, but I see there's a conflict. Could you please take a look at it? Thanks!

[rafmacalaba]

Hello @rafmacalaba , thank you for considering adding the centralized logging for the errors! Wanted to merge this, but I see there's a conflict. Could you please take a look at it? Thanks!

Fixed the conflicts! Thanks!