fix: friendly error messages for optional backend dependencies

[planetf1]

Misc PR

Type of PR

• Bug Fix
• New Feature
• Documentation
• Other

Description

• Link to Issue: Fixes sugg: friendly import errors for optional dependencies (pip install) #342

Summary

Improves the user experience for optional backends (hf, watsonx, litellm) by wrapping their imports in try/except ImportError blocks.

Problem

Previously, if a user ran start_session(backend="hf") without installing mellea[hf], they received a raw ModuleNotFoundError: No module named 'outlines'. This was confusing for new users who didn't know outlines is an internal dependency of the HuggingFace backend.

Solution

This PR catches the ImportError during the backend resolution phase and raises a cleaner ImportError that explicitly tells the user which extra to install.

Fixes

New Error Message:

The 'hf' backend requires extra dependencies. Please install them with: pip install 'mellea[hf]'

Note on Other Dependencies

• vLLM: Not used in start_session(), so users cannot trigger this crash. To fix this, we would first need to add "vllm" support to backend_name_to_class, and then wrap that new import in the same try/except block. That feels like a new feature so do it when adding?
• Docling: Usage is isolated to RichDocument, but requires refactoring top-level imports (lazy loading) to fix properly. Out of scope for this quick fix. Can add here for completeness but would mean a bigger change?
• Dev dependencies: Missing dev tools (e.g. pytest) will still raise standard errors.

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code as added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Verified in a clean virtual environment (Python 3.12) with no extra dependencies installed.

Test Script Output:

Click to see reproduction script (verify_fixes.py)

import mellea
import sys

def test_backend_import(backend_name):
    print(f"\n--- Testing backend: {backend_name} ---")
    try:
        # start_session internally calls backend_name_to_class which triggers the import
        mellea.start_session(backend_name=backend_name)
    except ImportError as e:
        msg = str(e)
        print(f"Caught Expected ImportError: {msg}")
        if "requires extra dependencies" in msg and f"mellea[{backend_name}]" in msg:
             print("SUCCESS: Friendly error message detected.")
        else:
             print("FAILURE: ImportError caught but message format is wrong!")
    except Exception as e:
        print(f"FAILURE: Caught unexpected exception type: {type(e).__name__}: {e}")
    else:
        print("FAILURE: No exception raised! (Did you install the extras by mistake?)")

if __name__ == "__main__":
    test_backend_import("hf")
    test_backend_import("watsonx")
    test_backend_import("litellm")

--- Testing backend: hf ---
Caught Expected ImportError: The 'hf' backend requires extra dependencies. Please install them with: pip install 'mellea[hf]'
SUCCESS: Friendly error message detected.

--- Testing backend: watsonx ---
Caught Expected ImportError: The 'watsonx' backend requires extra dependencies. Please install them with: pip install 'mellea[watsonx]'
SUCCESS: Friendly error message detected.

--- Testing backend: litellm ---
Caught Expected ImportError: The 'litellm' backend requires extra dependencies. Please install them with: pip install 'mellea[litellm]'
SUCCESS: Friendly error message detected.

[github-actions]

The PR description has been updated. Please fill out the template for your PR to be reviewed.

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert|release)(?:\(.+\))?:

[planetf1]

I think this helps setup for a user -- does it make sense? Any thoughts on docling/vllm (leaving as draft until agreed)

[jakelorocco]

I think putting this in start_session makes sense. If you are directly instantiating the backend, it's probably more clear what's going wrong.

[planetf1]

I think putting this in start_session makes sense. If you are directly instantiating the backend, it's probably more clear what's going wrong.

@jakelorocco Are you ok with where they are currently? they are in a method invoked only from start_session - it was the main init that it seemed would catch people out the most

We can add more checks - even for any import, but I was also wary of adding too much clutter.

What do you think about the vllm/docling aspect

• vllm isn't added since it doesn't currently get setup from start_session (but should be protected if/when it does)
• docling needs a little more changes. I could add that here (or another PR), or leave?

(Rebased)

[jakelorocco]

I think the PR is good as is. We can make changes to the backends as well, but I think those errors are more intuitive since you would be directly importing the backend in those scenarios.

I agree though; for the backends (vllm included), we should consider what this looks like at that level. And same for docling / other potential imports like that.

[planetf1]

Ok can go with this one, and I'll raise followups if I have a proposal on the others